npm - @bicharts/chart-mcp - Versions diffs - 0.6.114 → 0.6.116 - Mend

@bicharts/chart-mcp 0.6.114 → 0.6.116

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE.txt +2 -2
package/README.md +10 -0
package/dist/check-chart.mjs +104 -151
package/dist/index.mjs +154 -141
package/package.json +7 -3
package/skills/bic-charts/CHART-SHAPES.md +56 -55
package/skills/bic-charts/SKILL.md +144 -12

package/package.json CHANGED Viewed

@@ -1,10 +1,14 @@
 {
   "name": "@bicharts/chart-mcp",
-  "version": "0.6.114",
+  "version": "0.6.116",
   "description": "AI Data Components for Power BI, Excel, Fabric Apps and the web, over MCP: working what-if apps, interactive tables and bivariate maps first, plus about 90 everyday chart types, with selection and cross-filtering already wired. It profiles your table locally; the code it writes is yours and runs with no license.",
   "keywords": [
     "mcp",
     "modelcontextprotocol",
+    "ai-data-components",
+    "data-apps",
+    "widgets",
+    "maps",
     "charts",
     "d3",
     "dataviz",
@@ -47,8 +51,8 @@
   },
   "// dependencies": "NONE, deliberately. dist/ bundles every module the server uses, so a runtime dependency installs nothing it needs - it only makes npx fetch that package (and its tree) before the first start. Everything the bundle carries is a devDependency; scripts/verify-package.mjs fails the release if a dependency appears or a shipped file imports anything but Node's built-ins.",
   "devDependencies": {
-    "@bicharts/chart-host": "^0.6.113",
-    "@bicharts/shape-core": "^0.6.113",
+    "@bicharts/chart-host": "^0.6.116",
+    "@bicharts/shape-core": "^0.6.116",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "@types/node": "^26.6.5",
     "@types/papaparse": "^5.3.14",

package/skills/bic-charts/CHART-SHAPES.md CHANGED Viewed

@@ -15,58 +15,59 @@ on the same picture, not a looser one.
 | chart | needs | limits | renderers | good for |
 | --- | --- | --- | --- | --- |
 | 3D scatter plot | 3 continuous | needs 700x480 px | D3, Plotly | Three continuous measures whose joint structure is the question, on a tile large enough to turn. To read exact values off three or more measures, Pair plot (scatter matrix) and Parallel coordinates are both more precise |
-| Africa (Bubbles) | lat/lon | needs 400x300 px | D3 | Best for point, city, province or country data within Africa: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
-| Africa Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for country-level metrics when the countries are in Africa: sales, users, or population by country (keyed to country names or ISO codes) |
-| Africa Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 400x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in Africa, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
-| Animated bar chart | 1 categorical, 1 continuous, 5+ time points | <=40 categories, needs 360x300 px | D3 | Requires one categorical, one measure and a time column with 5 or more ordered periods; best for a leaderboard that changes over time (top products by year, teams by season, countries by decade) |
-| Animated treemap | 2 categorical, 1 continuous, 3+ time points | needs 800x560 px | D3 | Requires a 2-level categorical hierarchy plus an additive measure observed at 3 or more ordered time points |
+| Africa (Bubbles) | lat/lon | needs 294x300 px | D3 | Best for point, city, province or country data within Africa: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
+| Africa Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3 | Best for country-level metrics when the countries are in Africa: sales, users, or population by country (keyed to country names or ISO codes) |
+| Africa Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 294x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in Africa, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
+| Animated bar chart | 1 categorical, 1 continuous, 5+ time points | <=40 categories, needs 294x300 px | D3 | Requires one categorical, one measure and a time column with 5 or more ordered periods; best for a leaderboard that changes over time (top products by year, teams by season, countries by decade) |
+| Animated treemap | 2 categorical, 1 continuous, 3+ time points | needs 294x560 px | D3 | Requires a 2-level categorical hierarchy plus an additive measure observed at 3 or more ordered time points |
 | Animated World (Bubbles) | 3+ time points, lat/lon | needs 400x320 px | D3 | Best for a measure per place observed at 3 or more ordered time points - revenue by country by year, openings by city by quarter, throughput by port by month - when the question is how each place changed rather than where it ranks |
-| Animated World Choropleth | 1 categorical, 3+ time points, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for a country-level measure observed at 3 or more ordered time points — watch how sales, users, or population shift across countries year by year |
+| Animated World Choropleth | 1 categorical, 3+ time points, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3 | Best for a country-level measure observed at 3 or more ordered time points — watch how sales, users, or population shift across countries year by year |
 | Annotated heatmap | 2 categorical, 1 continuous | <=20 categories, needs 320x280 px | D3, Matplotlib, Plotly, Seaborn | Requires two variables: categorical × categorical with values |
 | Arc diagram | 2 categorical | <=50 nodes, needs 380x240 px | D3 | Best for 5-50 nodes and a sparse-to-medium-density set of pairwise relationships |
 | Area chart | 1 continuous | needs 360x280 px | D3, Matplotlib, Plotly, Seaborn | Requires ordered categories or time with a continuous variable |
-| Asia (Bubbles) | lat/lon | needs 400x300 px | D3 | Best for point, city, province or country data within Asia: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
-| Asia Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for country-level metrics when the countries are in Asia: sales, users, or population by country (keyed to country names or ISO codes) |
-| Asia Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 400x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in Asia, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
-| Autocorrelation plot | 1 continuous, 20+ time points | needs 400x300 px | D3, Matplotlib, Plotly, Statsmodels | Requires a datetime series with one continuous variable |
+| Asia (Bubbles) | lat/lon | needs 294x300 px | D3 | Best for point, city, province or country data within Asia: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
+| Asia Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3 | Best for country-level metrics when the countries are in Asia: sales, users, or population by country (keyed to country names or ISO codes) |
+| Asia Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 294x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in Asia, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
+| Autocorrelation plot | 1 continuous, 20+ time points | needs 294x300 px | D3, Matplotlib, Plotly, Statsmodels | Requires a datetime series with one continuous variable |
 | Bar chart (horizontal) | - | needs 360x280 px | D3, Matplotlib, Plotly, Seaborn | Requires one categorical and one numeric variable |
 | Bar chart (vertical) | - | needs 600x420 px | D3, Matplotlib, Plotly, Seaborn | Requires one categorical and one numeric variable |
 | Basic Sankey | 2 categorical, 1 continuous | <=80 categories, <=80 edges, needs 320x240 px | D3, Plotly | Requires two categorical (nodes) and a continuous variable |
 | Beeswarm chart | 1 categorical, 1 continuous | <=30 categories, needs 280x280 px | D3, Matplotlib, Plotly, Seaborn | Best for showing distribution density across small categorical sets |
 | Binned 2D heatmap | 2 continuous | needs 320x280 px | D3 | Best for dense scatter data where points overplot: thousands of observations of two continuous variables, where the question is where the mass is rather than where each point is |
 | Binned bubble matrix | 1 continuous | needs 320x300 px | D3, Matplotlib, Plotly, Seaborn | Two banded/categorical axes (or two continuous variables split into ranges) plus an aggregatable size measure per cell, with optional independent color. Choose this over a continuous Bubble chart when raw points would overplot into a blob, or when the axes are naturally grouped |
-| Bivariate USA Choropleth (by state) | 1 categorical, 2 continuous, geo: us-state-code/us-state-name | <=56 categories, needs 400x300 px | D3 | Best for two state-level measures that might disagree: revenue vs return rate, income vs cost of living, cases vs vaccinations - at least 24 states and two measures that do not simply track each other |
+| Bivariate USA Choropleth (by state) | 1 categorical, 2 continuous, geo: us-state-code/us-state-name | <=56 categories, needs 294x300 px | D3 | Best for two state-level measures that might disagree: revenue vs return rate, income vs cost of living, cases vs vaccinations - at least 24 states and two measures that do not simply track each other |
 | Bivariate World Choropleth | 1 categorical, 2 continuous, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for two country-level measures that might disagree: wealth vs inequality, revenue vs margin, cases vs deaths - at least 24 countries and two measures that do not simply track each other |
 | Box plot | 1 continuous | needs 460x340 px | D3, Matplotlib, Plotly, Seaborn | Requires one continuous variable (plus optional category) |
 | Bubble chart | 3 continuous | needs 520x380 px | D3, Matplotlib, Plotly, Seaborn | Three continuous variables (x, y, size); one mark per row on continuous axes. If you want both axes grouped into bands with one aggregated bubble per cell, pick Binned bubble matrix instead |
-| Budget allocator | 1 categorical, 2 continuous | needs 560x380 px | D3 | One spend measure and one outcome by channel and period - monthly spend and signups for five marketing channels, budget and sales by region - with at least eight periods per channel |
+| Budget allocator | 1 categorical, 2 continuous | needs 440x380 px | D3 | One spend measure and one outcome by channel and period - monthly spend and signups for five marketing channels, budget and sales by region - with at least eight periods per channel |
 | Bullet chart | 1 continuous, a reference value | needs 220x120 px | D3, PLOTLY | Best for actual-vs-target KPIs with thresholds (revenue vs goal, SLA vs target) — a denser, clearer replacement for gauges |
 | Bump chart | 1 categorical, 1 continuous, 3+ time points | <=15 categories, needs 320x280 px | D3, PLOTLY | Best for leaderboard/position dynamics: how a handful of regions, products, or teams change rank quarter to quarter |
 | Calendar heatmap | 1 continuous, 60+ time points | needs 600x420 px | D3, Matplotlib, Plotly, Seaborn | Requires daily datetime data with associated numeric values; best for activity/contribution tracking over time |
-| Candlestick chart | 4 continuous, 10+ time points | needs 600x420 px | D3, Matplotlib, Plotly | Best for financial or trading data |
+| Candlestick chart | 4 continuous, 10+ time points | needs 294x420 px | D3, Matplotlib, Plotly | Best for financial or trading data |
 | Card | 1 continuous | needs 100x60 px | D3, Plotly | One numeric value that summarizes the dataset; small viewports |
 | Card with embedded | 1 continuous | needs 200x120 px | D3 | One headline value that deserves one more channel beside it: attainment with its target, a metric with its history, a profile of a few comparable scores, or a total with its split across up to eight categories; small tiles |
 | Card with multiple KPI | 2 continuous | needs 180x100 px | D3, Plotly | Multiple independent numeric metrics that should be surfaced together; KPI dashboards; long-narrow / short-wide viewports |
 | Card with sparkline | 1 continuous | needs 140x80 px | D3, Plotly | One numeric metric trending over an ordered dimension; small viewports |
-| Chord diagram | 2 categorical, 1 continuous | <=25 categories, <=30 nodes, needs 320x320 px | D3 | Requires matrix data showing bidirectional flows between entities; best for migration, trade, or relationship intensity data |
-| Circular heatmap | 1 categorical, 1 continuous | <=60 categories, needs 520x380 px | D3, Matplotlib, Plotly | Requires two dimensions - a cyclical one such as hour, weekday or month around the angle and a second category or date for the rings - and one measure for the colour |
+| Chord diagram | 2 categorical, 1 continuous | <=25 categories, <=30 nodes, needs 294x320 px | D3 | Requires matrix data showing bidirectional flows between entities; best for migration, trade, or relationship intensity data |
+| Circular heatmap | 1 categorical, 1 continuous | <=60 categories, needs 294x380 px | D3, Matplotlib, Plotly | Requires two dimensions - a cyclical one such as hour, weekday or month around the angle and a second category or date for the rings - and one measure for the colour |
 | Clustered heatmap | 2 categorical, 1 continuous | <=50 categories, needs 320x320 px | Plotly | Requires two variables for matrix values |
 | Connected scatterplot | 2 continuous, 6+ time points | needs 300x300 px | D3, PLOTLY | Best for the joint trajectory of two related metrics over time (e.g. units vs revenue, unemployment vs inflation) where the path shape is the insight |
 | Custom small multiples | 1 categorical, 1 continuous | <=16 categories, needs 320x240 px | D3, Matplotlib, Plotly, Seaborn | Best when comparing patterns across categories |
 | Cutoff tuner | 1 continuous | needs 560x360 px | D3 | One row per case with a model score or rating and the actual yes/no outcome - churn, fraud, default, conversion - when the question is where to draw the line and what each choice costs |
 | Cycle plot | 1 continuous, 24+ time points | needs 320x280 px | D3, PLOTLY | Best for multi-year monthly/quarterly/weekly data where the question is seasonality vs trend ('is Q4 always highest, and is each Q4 growing?') |
+| Decomposition cards | 2 categorical, 1 continuous | needs 294x200 px | D3 | One measure that adds up and two or more category fields; a second measure shows each card's change |
 | Delta KPI | 2 continuous | needs 200x120 px | D3 | Two comparable measures, or one measure at two points in time - this period against last, actual against plan, after against before |
 | Dendrogram (tree diagram) | 2 categorical, 1 continuous | <=60 leaves, needs 320x240 px | D3, Plotly | Best for 2-4 hierarchy levels with ≤ ~80 leaves |
 | Density contour plot | 2 continuous | needs 600x420 px | D3, Matplotlib, Plotly, Seaborn | Requires two continuous variables |
 | Donut chart | 1 categorical | <=10 categories, needs 520x380 px | D3, Matplotlib, Plotly | Requires one categorical variable with proportions |
 | Dumbbell chart | 1 categorical, 2 continuous | needs 600x420 px | D3, Plotly | Best for before/after or comparison scenarios |
-| ECDF plot | 1 continuous | needs 299x283 px | D3, Matplotlib, Plotly, Seaborn, Statsmodels | Requires one continuous variable |
+| ECDF plot | 1 continuous | needs 294x283 px | D3, Matplotlib, Plotly, Seaborn, Statsmodels | Requires one continuous variable |
 | Error band | 1 continuous | needs 360x240 px | D3 | Best for repeated measurements over time or over a continuous axis: latency trials, sensor readings, A/B metrics - anywhere the SPREAD matters as much as the average |
-| Error bar plot | 1 categorical, 1 continuous | needs 460x340 px | D3, Matplotlib, Plotly, Seaborn | Requires a category and a measure with a spread to show - repeated rows per category or a second measure holding the error |
-| Europe (Bubbles) | lat/lon | needs 400x300 px | D3 | Best for point, city, province or country data within Europe: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
-| Europe Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for country-level metrics when the countries are in Europe: sales, users, or population by country (keyed to country names or ISO codes) |
-| Europe Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 400x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in Europe, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
-| Event plot | 1 continuous | needs 400x300 px | D3, Matplotlib, Plotly, Seaborn | Requires a date or ordered value for each event, with an optional category that splits the events into lanes |
+| Error bar plot | 1 categorical, 1 continuous | needs 294x340 px | D3, Matplotlib, Plotly, Seaborn | Requires a category and a measure with a spread to show - repeated rows per category or a second measure holding the error |
+| Europe (Bubbles) | lat/lon | needs 294x300 px | D3 | Best for point, city, province or country data within Europe: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
+| Europe Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3 | Best for country-level metrics when the countries are in Europe: sales, users, or population by country (keyed to country names or ISO codes) |
+| Europe Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 294x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in Europe, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
+| Event plot | 1 continuous | needs 294x300 px | D3, Matplotlib, Plotly, Seaborn | Requires a date or ordered value for each event, with an optional category that splits the events into lanes |
 | Flippable multi-card | 1 continuous | <=12 categories, needs 180x120 px | D3 | Best when more headline numbers compete for one tile than fit at once: several measures side by side, or one or two measures paged through a small category, with the details on hover |
 | Funnel chart | 1 continuous | <=12 categories, needs 460x340 px | D3, PLOTLY | Best for conversion/attrition pipelines: signup funnels, sales pipeline stages, checkout flow drop-off |
 | Gantt chart | 1 categorical, 2 temporal | <=60 categories, needs 420x260 px | D3 | Best for project and phase schedules: tasks with a start and an end date, optionally grouped by phase, workstream or owner |
@@ -78,8 +79,8 @@ on the same picture, not a looser one.
 | Horizon chart | 1 categorical, 1 continuous, 12+ time points | needs 800x560 px | D3, Matplotlib, Plotly | Best for dense time series dashboards |
 | Horizontal/vertical span plot | 1 categorical, 2 continuous | needs 400x300 px | D3, Matplotlib, Plotly, Seaborn | Requires a category and two numeric bounds per category - a low and a high, or a start and an end - on one shared scale |
 | Icicle plot | 2 categorical, 1 continuous | <=60 leaves, needs 320x240 px | D3, Plotly | Best for 2-4 levels of hierarchy with ≤ ~50 leaves; an alternative to a sunburst when horizontal/vertical scanning is preferred |
-| Interactive table | - | needs 320x200 px | D3 | Any set of rows and columns that a reader wants to scan, sort and look into - an account list, a roster, a task or ticket list, a ledger, results with a status and a score; long lists a chart would crowd |
-| Joint plot | 2 continuous | needs 360x280 px | D3, Matplotlib, Plotly, Seaborn | Requires two continuous variables |
+| Interactive table | - | needs 294x200 px | D3 | Any set of rows and columns that a reader wants to scan, sort and look into - an account list, a roster, a task or ticket list, a ledger, results with a status and a score; long lists a chart would crowd |
+| Joint plot | 2 continuous | needs 294x280 px | D3, Matplotlib, Plotly, Seaborn | Requires two continuous variables |
 | KDE plot (1D & 2D) | 1 continuous | needs 400x300 px | D3, Matplotlib, Plotly, Seaborn, Statsmodels | Requires one continuous variable (or two for 2D KDE) |
 | Lag plot (scatter of value vs lag) | 1 continuous, 20+ time points | needs 280x280 px | D3, Matplotlib, Plotly, Seaborn, Statsmodels | Requires a datetime series with one continuous variable |
 | Line chart | 1 continuous | needs 400x300 px | D3, Matplotlib, Plotly, Seaborn | One or more continuous series over an ordered/temporal axis |
@@ -87,20 +88,20 @@ on the same picture, not a looser one.
 | Lollipop chart | 1 categorical, 1 continuous | <=50 categories, needs 700x480 px | D3, PLOTLY | Best as a cleaner bar replacement for ranking many categories by a single measure |
 | Marimekko / Mosaic plot | 2 categorical, 1 continuous | needs 320x280 px | D3 | Best for 3-10 outer × 3-10 inner categories with a positive measure |
 | Mermaid diagram | 1 categorical | <=150 categories, needs 360x240 px | D3 | A source and a target column (a process, a hand-off chain, a dependency list), two to four nested categories (an org or product hierarchy), or a date beside an event name (milestones, releases, history) - up to a few dozen boxes |
-| Middle East Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for country-level metrics when the countries are in the Middle East: sales, users, or population by country (keyed to country names or ISO codes) |
-| Motion bubble chart | 1 categorical, 2 continuous, 3+ time points | <=40 categories, needs 360x320 px | D3 | Requires one categorical whose members are the bubbles, two measures for position and a time column with 3 or more ordered periods; best for watching entities travel - plans by subscribers and churn, countries by wealth and lifespan, teams by cost and output |
+| Middle East Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3 | Best for country-level metrics when the countries are in the Middle East: sales, users, or population by country (keyed to country names or ISO codes) |
+| Motion bubble chart | 1 categorical, 2 continuous, 3+ time points | <=40 categories, needs 294x320 px | D3 | Requires one categorical whose members are the bubbles, two measures for position and a time column with 3 or more ordered periods; best for watching entities travel - plans by subscribers and churn, countries by wealth and lifespan, teams by cost and output |
 | Multi-level Sankey | 3 categorical, 1 continuous | <=80 edges, needs 420x280 px | D3, Plotly | Requires three (or more) categorical and one continuous variable |
 | Network diagram | 2 categorical | <=150 categories, <=80 edges, needs 320x280 px | D3, Matplotlib | Requires node and edge data (source-target pairs); best for relationship, dependency, or social network visualization |
-| Normalized stacked bar chart | 2 categorical, 1 continuous | needs 600x420 px | D3 | Best with two categoricals and one additive measure when the question is what the composition is rather than how big the total is |
-| North America (Bubbles) | lat/lon | needs 400x300 px | D3 | Best for point-located data with latitude and longitude columns: stores, cities, facilities, or events across North America, with a measure for bubble size and optionally a second measure or category for color |
-| North America Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for country-level metrics when the countries are in North America: sales, users, or population by country (keyed to country names or ISO codes) |
-| North America Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon/us-state-code/us-state-name | <=2000 categories, needs 400x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in North America, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
-| Oceania (Bubbles) | lat/lon | needs 400x300 px | D3 | Best for point, city, province or country data within Oceania: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
-| Oceania Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for country-level metrics when the countries are in Oceania: sales, users, or population by country (keyed to country names or ISO codes) |
-| Oceania Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 400x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in Oceania, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
-| Origin-Destination Flow Map | lat/lon | needs 400x300 px | D3 | Best for movement between places: flight routes, shipping and trade lanes, migration, commutes or transfers, where each row names where something started and where it ended plus a measure of how much moved |
+| Normalized stacked bar chart | 2 categorical, 1 continuous | needs 340x420 px | D3 | Best with two categoricals and one additive measure when the question is what the composition is rather than how big the total is |
+| North America (Bubbles) | lat/lon | needs 294x300 px | D3 | Best for point-located data with latitude and longitude columns: stores, cities, facilities, or events across North America, with a measure for bubble size and optionally a second measure or category for color |
+| North America Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3 | Best for country-level metrics when the countries are in North America: sales, users, or population by country (keyed to country names or ISO codes) |
+| North America Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon/us-state-code/us-state-name | <=2000 categories, needs 294x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in North America, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
+| Oceania (Bubbles) | lat/lon | needs 294x300 px | D3 | Best for point, city, province or country data within Oceania: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
+| Oceania Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3 | Best for country-level metrics when the countries are in Oceania: sales, users, or population by country (keyed to country names or ISO codes) |
+| Oceania Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 294x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in Oceania, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
+| Origin-Destination Flow Map | lat/lon | needs 294x300 px | D3 | Best for movement between places: flight routes, shipping and trade lanes, migration, commutes or transfers, where each row names where something started and where it ended plus a measure of how much moved |
 | Packed circles | 2 categorical, 1 continuous | needs 280x280 px | D3 | Best with one numeric measure plus 1-2 categorical groupings producing 20-150 leaves |
-| Pair plot (scatter matrix) | 3 continuous | needs 480x400 px | D3, Matplotlib, Plotly, Seaborn | Requires at least three continuous variables |
+| Pair plot (scatter matrix) | 3 continuous | needs 400x400 px | D3, Matplotlib, Plotly, Seaborn | Requires at least three continuous variables |
 | Parallel coordinates | 3 continuous | needs 700x480 px | D3, Plotly | Best for 4-8 numeric dimensions and up to ~1000 rows (heavier overlap with more) |
 | Pareto chart | 1 categorical | <=30 categories, needs 320x280 px | D3, MATPLOTLIB, PLOTLY | Best for finding the vital few: defect/complaint/incident counts by cause, revenue concentration by product or customer (the 80/20 view) |
 | Pie chart | 1 categorical | <=10 categories, needs 280x280 px | D3, Matplotlib, Plotly | Requires one categorical variable with proportions |
@@ -108,46 +109,46 @@ on the same picture, not a looser one.
 | Progress ring | 1 continuous, a bounded scale | needs 160x160 px | D3 | A value against a ceiling the data states, overall or one ring per category, in a small or square tile - percent complete, attainment, utilisation; a constant value is a valid reading |
 | Radar (spider) chart | 1 continuous | <=8 axes, needs 700x480 px | D3, Matplotlib, Plotly | Requires multiple continuous variables across categories |
 | Range-compare time series | 1 continuous, 15+ time points | needs 480x320 px | D3 | Best for a single measure tracked over many dates when the story is a chosen window: drag the two handles to total a period and compare its endpoints, like revenue across a campaign or sensor readings around an incident |
-| Regression plot (line with CI) | 2 continuous | needs 520x380 px | D3, Matplotlib, Plotly, Seaborn, Statsmodels | Requires two continuous variables - a predictor and a response |
+| Regression plot (line with CI) | 2 continuous | needs 294x380 px | D3, Matplotlib, Plotly, Seaborn, Statsmodels | Requires two continuous variables - a predictor and a response |
 | Ridgeline plots | 1 categorical, 1 continuous | <=25 categories, needs 280x280 px | D3, Matplotlib, Plotly, Seaborn | Best with many observations per category |
-| Rose (Coxcomb) chart | 1 categorical | <=24 categories, needs 300x300 px | D3 | Best for cyclical or directional categories: wind direction, hour of day, month of year, compass sectors - anywhere the categories wrap around rather than running left to right |
-| Rotating carousel | 1 continuous | <=12 categories, needs 320x200 px | D3 | Best when each category value deserves its own small chart and the tile has room for only one at a time; the reader turns it, or it turns itself |
-| Rug plot | 1 continuous | needs 360x280 px | D3, Matplotlib, Plotly, Seaborn | Requires one continuous variable |
+| Rose (Coxcomb) chart | 1 categorical | <=24 categories, needs 294x300 px | D3 | Best for cyclical or directional categories: wind direction, hour of day, month of year, compass sectors - anywhere the categories wrap around rather than running left to right |
+| Rotating carousel | 1 continuous | <=12 categories, needs 294x200 px | D3 | Best when each category value deserves its own small chart and the tile has room for only one at a time; the reader turns it, or it turns itself |
+| Rug plot | 1 continuous | needs 294x280 px | D3, Matplotlib, Plotly, Seaborn | Requires one continuous variable |
 | Sankey alluvial flow | 2 categorical, 1 continuous | <=10 categories, <=80 edges, needs 420x280 px | D3, Matplotlib, Plotly | Requires at least two categorical variables |
 | Scatter plot | 2 continuous | needs 460x340 px | D3, Matplotlib, Plotly, Seaborn | Requires two continuous variables |
 | Seasonal decomposition | 1 continuous, 24+ time points | needs 320x360 px | Matplotlib, Plotly, Statsmodels | Requires a datetime series with one continuous variable and at least two full seasonal cycles |
-| Selection explainer | 2 continuous | needs 560x360 px | D3 | Two measures over thirty or more rows that also carry other fields - region, plan, tenure, size - when the question is 'what do these points have in common?' |
+| Selection explainer | 2 continuous | needs 294x360 px | D3 | Two measures over thirty or more rows that also carry other fields - region, plan, tenure, size - when the question is 'what do these points have in common?' |
 | Slope chart | 1 categorical, 1 continuous, 2+ time points | <=40 categories, needs 460x340 px | D3, PLOTLY | Best for two-period change across many categories: YoY by region/segment, before/after comparisons, ranking shifts between two snapshots |
-| South America (Bubbles) | lat/lon | needs 400x300 px | D3 | Best for point, city, province or country data within South America: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
-| South America Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3 | Best for country-level metrics when the countries are in South America: sales, users, or population by country (keyed to country names or ISO codes) |
-| South America Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 400x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in South America, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
+| South America (Bubbles) | lat/lon | needs 294x300 px | D3 | Best for point, city, province or country data within South America: stores, offices, customers or revenue by place, with a measure for bubble size and optionally a second measure or category for color |
+| South America Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3 | Best for country-level metrics when the countries are in South America: sales, users, or population by country (keyed to country names or ISO codes) |
+| South America Choropleth (by province) | 1 categorical, geo: admin1-code/admin1-name/city-name/city-name-world/latlon | <=2000 categories, needs 294x300 px, host-only: the Power BI visual and the Excel add-in, never this MCP | D3 | Best for metrics by province, state or region in South America, or by city when you want the cities summed into their provinces (keyed to province names, ISO codes or city names) |
 | Spiral plot | 1 continuous, 12+ time points | needs 320x320 px | D3, PLOTLY | Best for long, finely-grained, strongly periodic series (years of daily data) where the cyclic pattern is the story |
 | Stacked area chart | 1 categorical, 1 continuous | needs 460x340 px | D3, Matplotlib, Plotly | Requires ordered categories with multiple continuous series |
 | Stacked bar chart | 2 categorical, 1 continuous | needs 700x480 px | D3, Matplotlib, Plotly, Seaborn | Requires one categorical, one subcategory, and one numeric variable |
-| Stem plot | 1 continuous | needs 360x280 px | D3, Matplotlib, Plotly | Requires one measure read along an ordered sequence - a time step, a row index or an ordered category |
-| Step plot | 1 continuous | needs 460x340 px | D3, Matplotlib, Plotly, Seaborn | Requires ordered categories with one continuous variable |
+| Stem plot | 1 continuous | needs 294x280 px | D3, Matplotlib, Plotly | Requires one measure read along an ordered sequence - a time step, a row index or an ordered category |
+| Step plot | 1 continuous | needs 294x340 px | D3, Matplotlib, Plotly, Seaborn | Requires ordered categories with one continuous variable |
 | Streamgraph | 1 categorical, 1 continuous, 8+ time points | needs 520x380 px | D3, Plotly | Best with 3-12 categorical series and a continuous time axis with at least 15-30 evenly-spaced points |
 | Strip plot | 1 continuous | needs 700x480 px | D3, Matplotlib, Plotly, Seaborn | Requires one categorical and one continuous variable; jitter on the category axis prevents overplot at the same value |
 | Sunburst chart | 2 categorical, 1 continuous | needs 400x300 px | D3, Matplotlib, Plotly | Requires hierarchical categorical data |
-| Table with embedded | 1 categorical, 1 continuous | <=40 categories, needs 420x200 px | D3 | Best for a small set of items compared across several attributes at once (a forecast/roster/scorecard table) |
-| Ternary plot | 3 continuous | needs 320x320 px | D3 | Three measures that add up to the same total on every row - product mix, budget allocation, vote share, channel split |
+| Table with embedded | 1 categorical, 1 continuous | <=40 categories, needs 294x200 px | D3 | Best for a small set of items compared across several attributes at once (a forecast/roster/scorecard table) |
+| Ternary plot | 3 continuous | needs 294x320 px | D3 | Three measures that add up to the same total on every row - product mix, budget allocation, vote share, channel split |
 | Thermometer | 1 continuous, a bounded scale | needs 90x220 px | D3 | A value against a ceiling the data states, overall or one tube per category, in a tall narrow tile - a sidebar rail or a column of KPIs down a page edge; a constant value is a valid reading |
 | Time series plot | 1 continuous | needs 460x340 px | D3, Plotly | Requires a datetime axis with at least one continuous variable |
-| Trail | 2 continuous | needs 360x220 px | D3 | Best when a series has both a level and a weight: price with traded volume, sentiment with mention count, a metric with the sample size behind it |
+| Trail | 2 continuous | needs 294x220 px | D3 | Best when a series has both a level and a weight: price with traded volume, sentiment with mention count, a metric with the sample size behind it |
 | Treemap | 1 categorical, 1 continuous | needs 240x220 px | D3, Matplotlib, Plotly | Requires hierarchical categorical data with values |
 | US hex-tile cartogram | 1 categorical, geo: us-state-code/us-state-name | needs 400x300 px | D3 | Best with one row per US state and a single measure, when the question is which states are high or low rather than where they are |
-| USA Choropleth (by state) | 1 categorical, geo: us-state-code/us-state-name | <=56 categories, needs 400x300 px | D3 | Best for state-level US metrics: sales, users, or population by state, any measure that varies by US state (keyed to state names or USPS codes) |
-| USA Choropleth (by ZIP-3) | 1 categorical, geo: us-zip5 | <=42000 categories, needs 400x300 px | D3 | Best for regional US ZIP analysis: metrics by 3-digit ZIP prefix area, any measure that varies across US postal regions (keyed to 5-digit ZIP codes, grouped to their 3-digit prefix) |
-| Variance chart (budget vs actual) | 1 categorical, 2 continuous, a measure naming itself budget/plan/target | <=60 categories, needs 360x240 px | D3 | One category or period column plus two measures where one names itself the reference - Revenue and Revenue Budget, Cost and Cost Plan, Attained and Quota; finance reporting, budget reviews, plan attainment |
+| USA Choropleth (by state) | 1 categorical, geo: us-state-code/us-state-name | <=56 categories, needs 294x300 px | D3 | Best for state-level US metrics: sales, users, or population by state, any measure that varies by US state (keyed to state names or USPS codes) |
+| USA Choropleth (by ZIP-3) | 1 categorical, geo: us-zip5 | <=42000 categories, needs 294x300 px | D3 | Best for regional US ZIP analysis: metrics by 3-digit ZIP prefix area, any measure that varies across US postal regions (keyed to 5-digit ZIP codes, grouped to their 3-digit prefix) |
+| Variance chart (budget vs actual) | 1 categorical, 2 continuous, a measure naming itself budget/plan/target | <=60 categories, needs 294x240 px | D3 | One category or period column plus two measures where one names itself the reference - Revenue and Revenue Budget, Cost and Cost Plan, Attained and Quota; finance reporting, budget reviews, plan attainment |
 | Variance grid | 1 categorical, 2 continuous, a measure naming itself budget/plan/target | needs 320x200 px | D3 | One or more category columns plus two measures where one names itself the reference - Revenue and Revenue Budget, Cost and Cost Plan, Attained and Quota; a P&L, a budget review, plan attainment by unit; many rows or nested groups that a chart would crowd |
 | Violin plot | 1 continuous | needs 280x280 px | D3, Matplotlib, Plotly, Seaborn | Requires one continuous variable (plus optional category) |
 | Voronoi treemap | 2 categorical, 1 continuous | <=50 cells, needs 320x280 px | D3 | Best for 5-30 categories with one non-negative measure; an alternative to a plain treemap when the organic look is desired |
 | Waffle chart | 1 categorical, 1 continuous | <=6 categories, needs 520x380 px | D3, Matplotlib, Plotly | Best for showing part-to-whole relationships with small number of categories; more accurate than pie charts |
 | Waterfall chart | 1 continuous | <=20 categories, needs 360x280 px | D3, Matplotlib, Plotly | Best for financial data showing contribution to total (revenue bridges, P&L analysis, budget variance) |
-| What-if predictor | 3 continuous | needs 520x300 px | D3 | Three to ten numeric measures over at least thirty rows that move together - stores, products, campaigns, regions by quarter - when the question is 'if these were X and Y, what would the others likely be?'; an ordered rating or size and one category of up to six values can be pinned too |
-| What-if projection | 1 continuous, 6+ time points | needs 420x280 px | D3 | A dated measure with at least six periods when the question is what happens next under an assumption the reader chooses - revenue against a target, headcount, subscribers; bind a What-If parameter measure to drive the rate from a slicer |
-| What-if scenarios | 1 continuous, 6+ time points | needs 480x320 px | D3 | A dated measure with at least six periods when the question is how far apart the outcomes of several assumptions land - revenue under a range of growth rates, headcount, subscribers; bind a What-If parameter column to draw exactly the range you defined |
+| What-if predictor | 3 continuous | needs 400x300 px | D3 | Three to ten numeric measures over at least thirty rows that move together - stores, products, campaigns, regions by quarter - when the question is 'if these were X and Y, what would the others likely be?'; an ordered rating or size and one category of up to six values can be pinned too |
+| What-if projection | 1 continuous, 6+ time points | needs 294x280 px | D3 | A dated measure with at least six periods when the question is what happens next under an assumption the reader chooses - revenue against a target, headcount, subscribers; bind a What-If parameter measure to drive the rate from a slicer |
+| What-if scenarios | 1 continuous, 6+ time points | needs 294x320 px | D3 | A dated measure with at least six periods when the question is how far apart the outcomes of several assumptions land - revenue under a range of growth rates, headcount, subscribers; bind a What-If parameter column to draw exactly the range you defined |
 | Word cloud | 1 categorical | <=100 categories, needs 280x200 px | D3, Matplotlib, Plotly | Requires text data or pre-computed word-frequency pairs; best for qualitative text exploration |
-| World (Bubbles) | lat/lon | needs 400x300 px | D3 | Best for point or country-level data spanning more than one continent: offices, shipments, users or revenue by country, with a measure for bubble size and optionally a second measure or category for color |
-| World Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 400x300 px | D3, PLOTLY | Best for country-level metrics: sales, users, or population by country, any measure that varies by nation (keyed to country names or ISO codes) |
+| World (Bubbles) | lat/lon | needs 294x300 px | D3 | Best for point or country-level data spanning more than one continent: offices, shipments, users or revenue by country, with a measure for bubble size and optionally a second measure or category for color |
+| World Choropleth | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 294x300 px | D3, PLOTLY | Best for country-level metrics: sales, users, or population by country, any measure that varies by nation (keyed to country names or ISO codes) |
 | World tile-grid cartogram | 1 categorical, geo: country-iso3/country-iso2/country-name | <=250 categories, needs 510x420 px | D3 | Best with one row per country and a single measure, when the question is which countries are high or low rather than where they are |

package/skills/bic-charts/SKILL.md CHANGED Viewed

@@ -26,6 +26,13 @@ the call. Tell them a browser tab is about to open. If the call comes back with
 continue" and a link instead, give them that link, and call again once they've signed in. A key in
 the server's environment is only for machines with no browser, such as CI.
+**On the hosted server** (`https://bizintelligencechampions.com/mcp`, which the Claude Code plugin and claude.ai
+connect to), the tools can't reach the person's files: there is no `setup_fabric_app`, `query_semantic_model` or
+`suggest_charts`, and no `out_dir` or `csv_path`. Pass each table as `data` or `csv_text`; `generate_chart` returns the
+code, the rows and the binding in its reply, and you write them into the project. For a Fabric App, or charts written
+straight to disk, the person adds the local server (`claude mcp add bic-chart-local -- npx -y @bicharts/chart-mcp`) and
+the steps below apply as written.
 ## 0. Decide what to pull (only if you are starting from a data MODEL)
 Skip this if you already have a table. If you are holding a semantic model, a warehouse schema or
@@ -630,6 +637,19 @@ is:
 blank), `check_app` flags them in the app's `.dax` files, and `check_chart` warns when one value sets a diverging color
 scale's span.
+**A share of a whole is 0, not blank, where the whole is there.** `DIVIDE ( CALCULATE ( [Revenue], DimChannel[Channel] =
+"Partner" ), [Revenue] )` is blank for a country with revenue but no partner sales: the part is BLANK, and DIVIDE passes it
+on. A blank drops out of every rank, median and comparison of that field, so a Selection explainer comparing a circled
+group on its partner share leaves the 0% countries out and shows no gap. Add `+ 0` to the part, which keeps the share
+blank where the whole is (so SUMMARIZECOLUMNS still drops a row with no revenue at all):
+```dax
+"Partner Share", DIVIDE ( CALCULATE ( [Revenue], DimChannel[Channel] = "Partner" ) + 0, [Revenue] )   -- 0 with no partner sales
+```
+`COALESCE ( DIVIDE ( ... ), 0 )` reads 0 too, but keeps a row for every country, revenue or not. `query_semantic_model` and
+`check_app` flag a share written without either.
 **A chart's categories come from the data.** Group by the category column and let the chart take every value the
 model holds; never name the categories in the DAX one filter at a time (`CALCULATE([Sales], 'Channel'[Channel] =
 "Online")`, then "Retail", then "Partner"). A value the model adds or renames would drop out silently, and a chart that
@@ -666,6 +686,44 @@ card's words stay as written. Write the card's words and the query's bound toget
 projection, the window is the history it starts from, and its horizon is the chart's own control. `check_app` warns on a
 card that names a window over a query with no bound on it.
+**A query's range comes from the data or the person's words - never a date copied from a profile.** A window is in a
+query only because the person asked for it ("2025", "the last seven years"). Otherwise the range is the data's own: the
+first and last day a profile showed are where the data ran when you looked, and a query bounded to them drops every
+later week, silently, once the model holds one. Leave the dates out, or bound the range with the data's own first and
+last day, and print the range on the card from the rows the query returns, never as typed dates:
+```dax
+DATESBETWEEN ( 'Calendar'[Date],                                   -- the range the cases themselves cover
+    CALCULATE ( MIN ( 'Cases'[Opened Date] ), REMOVEFILTERS () ),
+    CALCULATE ( MAX ( 'Cases'[Opened Date] ), REMOVEFILTERS () ) )
+```
+REMOVEFILTERS keeps the range whole under a page pick, so a quiet week at either end still reads 0. `check_app` flags a
+query bounded by a date written into it: an error when the date is a day no one names a window by (a 25th, neither the
+1st nor the end of a month), and a warning when no card around a chart reading the query names that window.
+**A series over time returns every period in its range.** SUMMARIZECOLUMNS drops a row whose measures are all blank, so
+under a pick with sparse data (one owner, one product) a week with no cases has no row at all, and a line joins the
+weeks either side of it: a quiet week looks as busy as its neighbors. A count or sum reads 0 for an empty period, and a
+rate or ratio stays blank (there's nothing to divide), so the line drops to 0 for the count and breaks for the rate:
+```dax
+EVALUATE
+SUMMARIZECOLUMNS (
+    'Calendar'[Week],
+    DATESBETWEEN ( 'Calendar'[Date],                                                  -- the range the cases cover
+        CALCULATE ( MIN ( 'Cases'[Opened Date] ), REMOVEFILTERS () ),
+        CALCULATE ( MAX ( 'Cases'[Opened Date] ), REMOVEFILTERS () ) ),
+    "Cases Opened", COALESCE ( [Case Count], 0 ),                                    -- 0 in a quiet week
+    "SLA Compliance", DIVIDE ( [Cases In SLA], [Case Count] )                         -- blank in a quiet week
+)
+-- or let the period table drive: ADDMISSINGITEMS ( 'Calendar'[Week], SUMMARIZECOLUMNS ( ... ), 'Calendar'[Week] )
+```
+A COALESCE keeps every period of the period table, so bound the range with a filter on its date column: the data's own
+first and last day, as above, or the window the person asked for. `check_app` warns on a query a line over time reads
+that can drop a quiet period.
 **2. Profile and generate from THE WHOLE RESULT of that query - every row, never a few pasted in.**
 Eligibility reads row, region and category counts. A bivariate country map needs at least 24
 countries, so the same 40-country query shown as 8 sample rows hides it, and nothing fails - you are
@@ -705,6 +763,7 @@ without naming:
 | every place drawn at the same size, because which are high or low matters more than where | World tile-grid cartogram (or US hex-tile cartogram for states) |
 | actual against a budget, plan or target, with the gap shown for each period or unit | Variance chart (budget vs actual) |
 | that same actual-against-target comparison across many accounts or nested groups, read as a table with subtotals | Variance grid (a preview type) - it needs a category to group by; a date series alone is the Variance chart |
+| one total split into its parts level by level, with the reader choosing which field splits each level (a decomposition tree) | Decomposition cards (a preview type) - it needs a measure that adds up and two or more category fields; the opening, re-splitting and paging are drawn inside the chart |
 | a table with one row per item and each value DRAWN (bars, dots or icons in the cells), compact, for scanning down a column and nothing more | Table with embedded |
 | a table a reader WORKS with: sorts, drags column widths, copies cells out, hides columns, scrolls a wide table sideways with frozen columns or rows, opens a row's detail; plain values by default, and where the request asks, data bars, chips, icons, or one value compared with several others as bars (this week against its averages) | Interactive table (a preview type) - name the cells to draw in `prompt`; widths, sort and hidden columns are the reader's, kept through the host's view state |
 | circling a group of points to see what sets them apart from the rest | Selection explainer (a preview type) - the lasso and the comparison are drawn inside the chart; put the other fields to compare in the same table (which ones: below); on a page, give it `selects` so a circled group filters the page (step 6) |
@@ -722,7 +781,8 @@ group statistics (what the circled points share, against the rest) into the app
 Which other fields to put in its query: 4 to 8 a reader would ask about that can differ across the plot - segments and
 categories (region, main channel), mix shares (online, retail, partner), size (population, a revenue band), and one or two
 measures at most. Leave out row keys, the axes and fields that just track an axis (revenue beside marketing spend): the
-panel tests every field, and each extra field makes the test for every field stricter.
+panel tests every field, and each extra field makes the test for every field stricter. A share is 0 where its part has
+no rows (`DIVIDE ( CALCULATE ( [Revenue], ... ) + 0, [Revenue] )`): a blank share is left out of the comparison.
 A chart that draws its own rate control needs the history and the goal, not the model's what-if parameter:
 leave the parameter's table (a `'Price Change'[Price Change]` column, say) out of its query. Grouping by it repeats
@@ -831,9 +891,24 @@ function CountryMap({ table, onPick }) {          // table = the live query resu
   294 when no width is named), and if it doesn't fit, generate it again with `generate_chart` at `width: 294` (the
   engine's small-screen rules then apply). A minimum wider than the phone's box draws the chart wider than its card,
   so the card scrolls sideways and anything the chart keeps in place (a table's name column) scrolls away with it.
-  `check_app` warns on a `minChartWidth` above 294.
+  `check_app` warns on a `minChartWidth` above 294, except at or below the chart type's own minimum (next).
+- **The exception: a chart type's own minimum.** Some chart types can't be read narrower than a minimum of their own,
+  and it can be wider than a phone. `generate_chart` reports it (a "Minimum size" line, and `chartMinWidth` /
+  `chartMinHeight` on its result), and the component it writes beside the chart keeps it for you: given less, the
+  component draws the chart at its minimum inside a box that scrolls, so on a phone that one chart scrolls sideways
+  and never squashes. Set nothing for it. Never regenerate a chart type below its own minimum to fit a phone - it
+  comes back squashed - and `check_chart` draws it at its minimum, as the component does.
+- **From a laptop up, no chart scrolls sideways.** A phone scrolling a chart at its type's minimum is designed; a laptop
+  never should: at every width from 1024px, give each chart a card at least its minimum. A two-column grid leaves a card
+  about 436px at a 1024px page, and a three-column one about 358px at 1280px (after the page's padding, a `gap-5` and a
+  `p-4` card with a border), so a chart whose minimum is wider gets a row of its own at those widths (move its card out of
+  the grid, or `lg:col-span-2`), or a grid track at least its minimum plus the card's padding and border
+  (`minmax(544px, ...)` for a 510px chart in that card). `check_app` warns on a card narrower than its chart's minimum at
+  any width from 1024 to 1920px.
 - Take the actual size from the layout - percent, flex or grid `fr` - and never a fixed height smaller than the chart's
-  minimum.
+  minimum. A card of fixed height holds its title and subtitle too, at a phone's width: a subtitle that takes one
+  line on a desktop wraps to three on a phone, and the chart's cell loses those lines. `check_app` warns on a card whose
+  fixed height leaves its chart under its minimum on a phone.
 - Put `min-h-0` on every flex child between a card and its chart (`min-w-0` in a row). A flex item's default
   `min-height: auto` lets it grow past its card, and the card's `overflow-hidden` slices off the rest.
 - A chart with controls drawn inside it (sliders, steppers, a reset) gets its card's full width. Put a side panel that
@@ -879,12 +954,16 @@ what the pick matches: its query goes through `filterQuery` / `treatAs` (or `fil
 KPIs and tables included - a table that follows a click shows only the matching rows. The chart that was clicked keeps
 all its marks and highlights the pick: a chart never filters itself, so the reader can change the pick there. When the
 person names more than one chart to click ("on the map or in the table"), give each its own filter on the same key,
-and pass every panel's query through a `treatAs` for each of those filters but its own - one filter shared by two
-clicked charts leaves each unfiltered by the other's click:
+all in ONE `group`, and pass every panel's query through a `treatAs` for each of those filters but its own - one filter
+shared by two clicked charts leaves each unfiltered by the other's click. The group makes them one pick: a pick in one
+clears the others, so the most recent pick is the page's one pick; every member's chart shows it, so clicking it again in
+whichever panel shows it clears it; and only the member holding it is active (one chip, one scope line). Without the
+group they are separate picks, ANDed: a country picked on the map and then in the table is held twice, and clicking it
+again on the map leaves the page filtered by the table's. `check_app` flags filters on one key without a group.
 ```tsx
-const fromMap = useBicFilter("CountryIso3", { label: "Country (map)", display: "CountryName" });
-const fromTable = useBicFilter("CountryIso3", { label: "Country (table)", display: "CountryName" });
+const fromMap = useBicFilter("CountryIso3", { label: "Country (map)", display: "CountryName", group: "country" });
+const fromTable = useBicFilter("CountryIso3", { label: "Country (table)", display: "CountryName", group: "country" });
 const COUNTRY = "Geography[CountryIso3]";
 const mapQuery = filterQuery(MAP_DAX, treatAs(fromTable, COUNTRY));       // the map follows the table's pick
 const tableQuery = filterQuery(TABLE_DAX, treatAs(fromMap, COUNTRY));     // the table follows the map's
@@ -893,6 +972,12 @@ const kpiQuery = filterQuery(KPI_DAX, treatAs(fromMap, COUNTRY), treatAs(fromTab
 // <KpiChart ... scopedBy={[fromMap, fromTable]} />; every panel gets its query={...}
 ```
+**A list beside those panels follows the page's one pick, never the union of filters.** An "open items for the picked
+countries" panel, a count or an "Add" button reads the group members' keys
+(`[fromMap, fromTable].flatMap(f => f.keys)`), which with the group are that one pick. Separate filters' keys are a union
+the page never shows: a scatter's three circled countries and a map pick of one of them list all three beside a page
+narrowed to one.
 **A panel whose query takes a page filter passes that filter as `scopedBy`, so the chart says it's filtered.** Its rows
 arrive already narrowed, and the chart can't see a filter applied to its query: a KPI deck kept its region's title over
 one country's totals and ranked what the filter left. Given `scopedBy={country}` (or `scopedBy={[fromMap, fromTable]}`),
@@ -902,7 +987,9 @@ with `filterBy` needs nothing more, its component tells the chart itself. A pane
 figure it plots (each measure under `REMOVEFILTERS`, `ALL` or an `ALLEXCEPT` that drops the picked column, as the closed
 deal figures are under a stage pick) isn't narrowed by it: leave that pick out of its `scopedBy`, or apply it, or its
 scope line names a stage its marks never move for. `check_app` flags a `scopedBy` pick the panel's query removes from
-everything it plots.
+everything it plots. A query that takes only part of a pick's key (`treatAs(cell, "'Accounts'[Region]")` on a region x
+stage cell) names that part: `scopedBy={{ filter: cell, takes: ["Region"] }}` says "Europe", never "Europe · 3-Propose",
+and a stage-only pick adds nothing to that chart's line.
 `check_app` lists each chart's wiring - filtered query, highlight only, or none - and warns on a panel no click
 reaches, and on a filtered-query panel with no `scopedBy`. Say that list in your reply, with any panel you left whole and why, so a gap is seen before deploy.
@@ -923,7 +1010,8 @@ What the library does, so the page doesn't:
   filter, and `country.value` is its FIRST key only. Anything that names or acts on the pick (a panel heading, an "Add
   an item" button) reads `country.keys`: with one, name it (`country.text`); with more, say how many ("3 countries")
   and list them, and offer a one-mark action only while `country.keys.length === 1`. When several filters share a key
-  (one per clicked chart), read every one of them. `check_app` flags a `.value` read.
+  (one per clicked chart), read every one of them; they're in one `group`, so their keys are the page's one pick, never
+  a union. `check_app` flags a `.value` read.
 - **A label picks its own field.** On a chart of region by stage with a filter keyed `["Region", "PipelineStep"]`, a
   click on a region's axis label holds that region in ANY stage, not the stage tuples drawn at that moment: the key is
   `["EMEA", ANY_VALUE]` (`isAnyValue` tells a free column; both from `@bicharts/chart-host/react` or `/page`), the chip
@@ -1082,6 +1170,12 @@ when the form offers every account, list them with `ADDCOLUMNS ( SUMMARIZE ( 'Ac
 ... ), "Open Pipeline", [Revenue Open] )`. `check_app` flags a marker-hosting chart whose query drops rows the form can
 target.
+**Markers go on every page that shows what they mark.** When the request asks for markers "on the map and in the table"
+and more than one page has a map or a table of those things, every one of them carries the badges, unless the person named
+the page, and every one of those pages lets the reader add an item and open a marker's items. A reader who adds an item on
+one page and then opens another, the default page included, looks for the marker there too. Say which pages carry them
+in your reply.
 The files use the template's own tokens; restyle them as you like. The table and the permissions are created on
 the next `npx rayfin up`, and every later `rayfin up` applies entity changes.
@@ -1094,7 +1188,10 @@ files do:
 - **The name shown comes from the caller's token too**, never only from the browser: the name is the signed-in email,
   and the policy checks it with the id - `claims.sub.eq(item.createdById).and(claims.email.eq(item.createdBy))` - so a
   hand-made call with your own id and someone else's name is refused. (`claims.email` is the token's email claim; a
-  Rayfin function sees the same token as `ctx.accessToken`.)
+  Rayfin function sees the same token as `ctx.accessToken`.) A function that checks the name against that token reads
+  the email the way Rayfin's sign-in reads the session's: the `email` claim, else, on a managed-hosting token, which has
+  none, `xms_attr.<app>.rfn_email`. It never falls back to `preferred_username` or `upn`: the session's email never
+  comes from them, so where they differ the person's own email is refused, or a name passes that the policy refuses.
 - **When** is the server's clock, never the browser's: every write that records a time (an item created, an item
   marked done) goes through a Rayfin function that stamps it on the server. Rayfin's data layer (checked on 1.36.2) has
   no server-time default for a field (a `default` is a fixed value), so the browser never sends the time at all. The
@@ -1164,10 +1261,39 @@ const markDone = useCallback(async (taskId: string) => {
     ("Nothing open") before the rows are in.
   - A form's default that comes from data loading elsewhere (the item's owner) is adopted when it arrives, unless the
     reader has already chosen; a lookup behind a choice list that fails says so in the form.
-  - A due date takes `min={today}`, and the server function refuses a past one.
+  - A due date is a calendar day with no time zone, and both sides read "today" one way. The form gives the field
+    `min={today}` in the reader's own date (YYYY-MM-DD from `getFullYear()`, `getMonth()` and `getDate()`, never
+    `toISOString()`, which is UTC's). The server function refuses only a day already past everywhere: one before the date
+    at UTC-12 (`new Date(Date.now() - 12 * 3600_000).toISOString().slice(0, 10)`), the earliest calendar day still
+    current anywhere, so never UTC's today or its own. The server can't know the reader's time zone and mustn't trust one
+    the browser sends, and a server that refuses by UTC's today refuses the reader's today every evening west of UTC: the
+    form offers it, and the save fails with "can't be in the past".
   - Read what the page shows, not every row ever saved: bound the query with `.where(...)` and show the first page as it
-    lands. Bound the DONE items, by when they were done; never bound the open ones, least of all by their due date: the
+    lands on the FIRST load. **A reload keeps what's on screen until the whole reload has landed**, then swaps it in
+    one step: a reload (after a save, on window focus) that hands each page to the list as it arrives cuts the list to
+    its newest page, and the markers and open items beyond it vanish and come back. A reload that fails keeps the list it
+    had and says the refresh failed; it never replaces the list with an error. Bound the DONE items, by when they were done; never bound the open ones, least of all by their due date: the
     most overdue open item is the one the reader most needs, and a due-date window drops it first.
+  - **The panel keeps the rows beside a refresh error, too.** A hook that keeps its rows and sets one `error` on any
+    failed load still loses the list when the panel renders `error ? <p>...</p> : <List />`: one failed refresh (a
+    network blip as the tab regains focus) hides every row and its Mark done button, under a line that may even say the
+    last ones are shown. Have the hook return the two failures apart, and show the load error in place of the rows only
+    while nothing has loaded:
+```ts
+// in the hook's reload: the first load has nothing to keep; a later one keeps the list it had
+} catch (e) {
+  if (mine !== seq.current) return;
+  if (loaded.current) setRefreshError(message(e)); else setLoadError(message(e));
+}
+// in the panel
+{loadError ? <p role="alert">The items couldn't load: {loadError} <button onClick={reload}>Retry</button></p>
+  : !loaded ? <p>Loading...</p>
+  : <>{refreshError ? <p role="status">Couldn't refresh ({refreshError}); showing the last ones loaded.</p> : null}
+      <ItemList items={open} /></>}
+```
+    `check_app` flags a panel that shows a refreshing hook's error in place of its rows.
   - A panel whose query failed offers Retry: setup's `BicChartPanel` does, from the query hook's `refetch` (pass the
     hook's whole result).
   - A disabled Save says why, beside it ("Pick a country from the list", "The due date can't be in the past"), tied to
@@ -1188,6 +1314,12 @@ const markDone = useCallback(async (taskId: string) => {
     in the form: an owner-of-each-account lookup run for the flag form also places the table's badges and fills the
     follow-ups list, so while it loads, or after it fails, those read as truly empty unless the page says why. A blank
     model value is left out of text, never put in with `String()`: `String(null)` prints "null".
+  - A lookup's rows (any query no chart draws: a form's choice list, every account with its owner) are read by column
+    name with `queryRows(result.data)` from `@bicharts/chart-host/dax`: `row["Account Number"]` for
+    `Accounts[Account Number]`, `row["Total"]` for `[Total]`. Never parse the `Table[Column]` headers yourself, and
+    write source with the file tools, never through a shell heredoc into a script: a pattern that passes through a
+    shell and a script loses its backslashes, and every option reads blank while the tests and the type check pass.
+    `check_app` flags a hand-written header reader.
   - Other people's writes show without a page reload: the hook reloads when the page comes back into view
     (`visibilitychange` to visible, and window `focus`), never on a timer, and a write that happens once (a done)
     reloads whether it succeeds or is refused (`try { await markDone() } finally { await reload() }`), so a refusal