@bicharts/chart-mcp 0.6.57 → 0.6.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-mcp",
-  "version": "0.6.57",
+  "version": "0.6.59",
   "description": "MCP (Model Context Protocol) stdio server for BIC AI charts: profile a dataset locally, then generate chart code that has passed the BIC backend's render gates. Works with any MCP-capable client (Claude Code, Claude Desktop, Cursor, Copilot Studio). An account pays to author charts; the code it writes is yours and runs with no licence.",
   "keywords": [
     "mcp",
@@ -43,8 +43,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.56",
-    "@bicharts/shape-core": "^0.6.56",
+    "@bicharts/chart-host": "^0.6.59",
+    "@bicharts/shape-core": "^0.6.59",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@types/node": "^20.0.0",
     "@types/papaparse": "^5.3.14",

package/skills/bic-charts/SKILL.md

@@ -468,7 +468,9 @@ Add `@using MyCharts.Components` to `_Imports.razor`, then on a page:
 
 A Fabric App built from Rayfin's `dataapp` template is a React app over a semantic model. The golden
 path above applies unchanged; these are the places a data app differs, each one measured on a real
-build.
+build. Everything here layers on the template's own AGENTS.md and skills - follow them for everything
+this doesn't cover. The template's visuals skill asks before using another chart library: a request
+for RegiaBI charts is that consent.
 
 **0. Once, right after scaffolding: `setup_fabric_app`.** It installs `@bicharts/chart-host` and `d3`, adds
 `src/lib/bic-chart-options.ts` (`useBicChartOptions()`: the app's Fabric theme - palette, foreground,
@@ -479,9 +481,14 @@ npm's latest, the release `rayfin init` installs, so run it before `rayfin init`
 (`rayfin init` installs the latest of only some packages, which leaves two copies of `rayfin-auth` on any other version).
 Its reply lists every `package.json` range it changed and names the Rayfin version installed; an app already on npm's
 latest is left alone. It fixes the template's own `scripts/validate-visual.spec.mjs`, which fails under ESM on a fresh
-scaffold (its reply says so), and adds
+scaffold (its reply says so). It reads the theme through `src/lib/bic-css-theme.ts` - Microsoft's own `useCssTheme`
+logic on `@microsoft/fabric-visuals-core` - and points the template's `src/main.tsx` at it, because importing the hook
+from `@microsoft/fabric-visuals` bundles Vega into an app that doesn't chart with it (about half its download); the
+reply names the one line it changed. It adds
 `.agents/skills/regiabi-charts/SKILL.md` beside the template's skills, for agents that read that folder. It never
-overwrites a file, and its reply ends with a worked example.
+overwrites a file, and its reply ends with a worked example. Building notes on marks or saved scenarios? Once Rayfin's
+data service is on (the notes recipe below, step a), run it again with `features: ["notes", "scenarios"]`: it writes
+those files finished.
 
 **1. Pull each chart's rows at the chart's GRAIN, with a query written for that chart.** One row per
 country for a country map, one per route for a flow map, one per month for a trend. The template's
@@ -496,15 +503,15 @@ simply offered other charts. Save the result to a file and pass `csv_path`, or p
 `data`.
 
 **3. Rename the query's columns to plain names first, and keep the map.** Results come back as
-`DimCountry[CountryCode]` and `[Revenue per Capita]`. Generate on `CountryCode` and
-`RevenuePerCapita`, and apply the SAME rename to the live rows at run time - the chart reads columns by
+`Geography[CountryIso3]` and `[Average Daily Rate]`. Generate on `CountryIso3` and
+`AverageDailyRate`, and apply the SAME rename to the live rows at run time - the chart reads columns by
 name. Pass the model's metadata as you rename: `isMeasure`, `format` and `description` (from
 `INFO.VIEW.MEASURES()` / `INFO.VIEW.COLUMNS()`) go on each column in `data`, which is the context a
 Power BI visual gets for free. In `INFO.VIEW.COLUMNS()` a column's name is `[Name]`, not `[Column]`.
 
 **Steps 1-3 are one call: `query_semantic_model`.** Give it the chart's DAX (`dax`, or a `.dax` file) and a
 `name`; it runs the query through the project's own `fabric-app-data` CLI, renames the headers (dropping the
-table and any symbols: `[Return Rate %]` becomes `ReturnRate`), saves every row to `.bic/data/<name>.csv`,
+table and any symbols: `[Occupancy %]` becomes `Occupancy`), saves every row to `.bic/data/<name>.csv`,
 reads each column's role, format and description from the model (`INFO.VIEW.MEASURES()` / `INFO.VIEW.COLUMNS()`),
 and profiles the result. Its reply ends with the arguments for the next two calls - `csv_path`, `measures`,
 `dimensions`, `formats`, `descriptions` - so pass them to `list_eligible_charts` and `generate_chart` as they
@@ -517,14 +524,19 @@ without naming:
 
 | the request sounds like | ask for |
 | --- | --- |
-| "compare A with B by country" | Bivariate World Choropleth |
-| "the shipping lanes / flows between countries" | Origin-Destination Flow Map |
-| "a projection I can steer with a growth rate, against our target" | What-if projection - the rate and horizon sliders are drawn inside the chart; there is no slider to build |
-| "how far apart the outcomes of several growth rates land" | What-if scenarios |
+| two measures compared across countries or states | Bivariate World (or USA) Choropleth |
+| movement, routes or flows between places | Origin-Destination Flow Map |
+| a forecast the reader steers with an assumption (a rate, a price change), against a goal | What-if projection - its sliders are drawn inside the chart; there is no slider to build |
+| how far apart the outcomes of several assumptions land | What-if scenarios |
 
 If the list doesn't offer what you expected, read its notes: it names a type refused on a count
 when your table is small, and it says when `name_filter` hid description matches.
 
+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
+every period once per parameter value - 12 months by 17 values is 204 rows for 12 points - and the chart's own
+slider sets the rate anyway.
+
 **5. Render live rows through the group, with the binding the generation returned.** The template
 queries at run time (`useSemanticModelQuery`), so the payload is rebuilt from live rows every time -
 never hand-built. **With `out_dir`, a D3 chart arrives with `chart.component.tsx` beside `chart.js`: a component that
@@ -534,17 +546,18 @@ headers onto the chart's plain names. Use it as it is:
 
 ```tsx
 // The component is named after the chart type ("Bivariate World Choropleth" -> BivariateWorldChoroplethChart).
-import { BivariateWorldChoroplethChart, rowsFromTable } from "@/charts/country-map/chart.component";
+import { BivariateWorldChoroplethChart, rowsFromTable } from "@/charts/occupancy-map/chart.component";
 
 import { BicChartPanel } from "@/components/bic-chart-panel";
 import { useBicChartOptions } from "@/lib/bic-chart-options";
+import QUERY from "@/queries/overview/occupancy-map.dax?raw";   // the template's rule: DAX lives in .dax files
 
 const result = useSemanticModelQuery({ connection: "<alias>", query: QUERY });  // the DAX it was generated on
 const options = useBicChartOptions();
+const country = useBicFilter("CountryIso3", { label: "Country", display: "CountryName" });   // step 6
 <BicChartPanel result={result}>
   {(table, size) => (                                // table = the live { columns, rows } result
-    <BivariateWorldChoroplethChart table={table} {...size} options={options}
-      onSelectRows={picked => onPick(picked[0]?.CountryCode ?? null)} />
+    <BivariateWorldChoroplethChart table={table} {...size} options={options} selects={country} />
   )}
 </BicChartPanel>
 ```
@@ -555,13 +568,13 @@ host by hand instead - `generate_chart` returns `binding`; pass all three:
 ```tsx
 import * as d3 from "d3";
 import { BicChart, BicChartGroup } from "@bicharts/chart-host/react";
-import code from "@/charts/country-map/chart.js?raw";
+import code from "@/charts/occupancy-map/chart.js?raw";
 // Saved from the generate_chart result: columns = data.columns, binding = binding, geoKind = geo.kind.
-import { columns, binding, geoKind } from "@/charts/country-map/meta";
+import { columns, binding, geoKind } from "@/charts/occupancy-map/meta";
 
 // The SAME rename the chart was generated on.
-const RENAME = { "DimCountry[CountryCode]": "CountryCode", "DimCountry[Country]": "Country",
-                 "[Revenue per Capita]": "RevenuePerCapita", "[Return Rate %]": "ReturnRate" };
+const RENAME = { "Geography[CountryIso3]": "CountryIso3", "Geography[CountryName]": "CountryName",
+                 "[Average Daily Rate]": "AverageDailyRate", "[Occupancy %]": "Occupancy" };
 
 function CountryMap({ table, onPick }) {          // table = the live query result
   const rows = table.rows.map(r => Object.fromEntries(
@@ -571,7 +584,7 @@ function CountryMap({ table, onPick }) {          // table = the live query resu
                    geo={binding.geo} point={binding.point} destination={binding.destination}>
       <BicChart id="map" code={code} d3={d3} geoKind={geoKind}
                 options={{ width, height }}
-                onSelect={idxs => onPick(idxs.length ? rows[idxs[0]].CountryCode : null)} />
+                onSelect={idxs => onPick(idxs.length ? rows[idxs[0]].CountryIso3 : null)} />
     </BicChartGroup>
   );
 }
@@ -587,7 +600,9 @@ function CountryMap({ table, onPick }) {          // table = the live query resu
 **Layout: a chart is never clipped or squashed.** Charts sit in cards, and a card is where they get cut off.
 - Render every chart inside `BicChartPanel`. It sizes the chart from its cell, never from the chart.
 - Give each chart its minimum: `minChartWidth` and `minChartHeight` (a world map about 560 x 300; a time series wants
-  height). Below that the panel scrolls; it never squashes or clips the chart.
+  height). Below that the panel scrolls; it never squashes or clips the chart. That scroll is a safety net, not a layout:
+  inside a page that already scrolls it's a second scrollbar, which reads as broken - size every chart's cell at or above
+  its minimum so it never shows.
 - Take the actual size from the layout - percent, flex or grid `fr` - and never a fixed height smaller than the chart's
   minimum.
 - 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
@@ -595,15 +610,70 @@ function CountryMap({ table, onPick }) {          // table = the live query resu
 - A chart with controls drawn inside it (sliders, steppers, a reset) gets its card's full width. Put a side panel that
   goes with it - saved scenarios, notes, a form - below the chart, not beside it: beside it, the chart's cell drops
   under its minimum and the panel scrolls.
-- When you stack a panel below a chart, don't keep a fixed card height that can't hold both: let the card grow (a
-  `min-h-*` in place of its `h-*`), or give the panel below `min-h-0 flex-1 overflow-auto` so it scrolls inside the card.
+- When you stack a panel below a chart, don't keep a fixed card height that can't hold both. Prefer letting the card grow
+  (a `min-h-*` in place of its `h-*`); only where the card must stay fixed, give the panel below `min-h-0 flex-1
+  overflow-auto` so it scrolls inside the card. The chart's own cell keeps a DEFINITE height (as the template's
+  app-validation skill asks); only the card around it and the panel below may grow.
+- One frame per chart: a RegiaBI chart sits in your card. The template's `VisualContainer` frames its `VegaVisual`
+  charts; don't put a second frame around one of ours.
   Give the chart's cell at least the chart's `minChartHeight` (`h-72` is 288px, under a 300 minimum).
 
-**6. Cross-filter across queries by KEY, not by row.** Charts fed by different queries don't share a
-row space, so one group can't span them. Put each query's charts in their own group, turn a click
-into the model's key (`CountryCode` above), keep it in app state, and filter the other queries with
-it. Anything saved against a mark - a note, a flag - is keyed the same way, never by `__rowIdx__`
-(see the row-index hazard above).
+**6. Filter the page with `useBicFilter` - never write a select handler, a toggle or a Clear.** A page filter is
+kept by the model's KEY (`CountryIso3`; a route's two ends), never by a row position, so it works across charts fed by
+different queries and survives a re-query. Hand it to the chart that sets it with `selects`; the rest of the page
+reads it:
+
+```tsx
+import { useBicFilter, BicFilterChips } from "@bicharts/chart-host/react";
+import { filterQuery, treatAs } from "@bicharts/chart-host/dax";
+import FORECAST_DAX from "@/queries/overview/bookings-forecast.dax?raw";
+
+// Once, in the page component, and passed down: each useBicFilter call is its own filter.
+const country = useBicFilter("CountryIso3", { label: "Country", display: "CountryName" });
+const route = useBicFilter(["OriginCode", "DestinationCode"],
+                          { label: "Route", display: ["OriginName", "DestinationName"] });
+const forecast = useSemanticModelQuery({ connection: "<alias>",
+  query: filterQuery(FORECAST_DAX, treatAs(country, "Geography[CountryIso3]")) });
+
+<BicFilterChips />                                   {/* "Country: Japan ×" - what's filtered, and its clear */}
+<BivariateWorldChoroplethChart table={countries} {...size} options={options} selects={country} />
+<OriginDestinationFlowMapChart table={routes} {...size} options={options} selects={route}
+  filterBy={{ filter: country, columns: ["OriginCode", "DestinationCode"] }} />
+```
+
+What the library does, so the page doesn't:
+- A click sets the filter. The same click again, or a click on empty canvas, clears it. Ctrl-click adds a key.
+- `country.clear()` (a button, a chip's ×) clears the filter AND the chart's marks.
+- New rows keep a selection whose key is still drawn and clear one whose key is gone - reported, never silent.
+- `country.value`, `country.values`, `country.keys`, `country.row` (the clicked row), `country.active` and
+  `country.text` ("Japan", or "Spain → Portugal" for a route) are what the page reads. For any OTHER key - a badge's,
+  a lane's end - `country.textOf(key, rows)` names it from a table that carries the display column.
+- Another chart whose table carries the key: `filterBy={{ filter: country, columns: [...] }}` on its component - any
+  of several columns, for a route that starts or ends there. It's applied inside the component, so the chart redraws
+  only when the filter or its data changes. A table WITHOUT the key column can't be filtered that way (it warns): filter
+  its query instead.
+- A query: `filterQuery(dax, treatAs(country, "Table[Column]"))` puts the filter into the `.dax` file's query the way
+  Microsoft's own data app skills do (CALCULATETABLE + TREATAS), escaped; with nothing selected the query is unchanged.
+  It adds a filter value and never changes the query's structure, so one `.dax` file serves both. A route filter maps
+  each end: `treatAs(route, "Routes[Origin]", "Routes[Destination]")`; `treatAs(route, "Geography[CountryIso3]")` takes
+  the route's FIRST column (its origin). Two filters on one column intersect: pass the one that should win.
+
+A Microsoft `VegaVisual` or `DataGrid` on the same page joins the same filter:
+`onInteraction={e => fromVegaInteraction(country, e)}` (`fromVegaInteraction` from `@bicharts/chart-host/react`; a page without React takes all of these from `@bicharts/chart-host/page`). It matches
+the event's field NAMES to the filter's columns, so name the VegaVisual's column `CountryIso3` too. It's one way: a
+page Clear clears the filter, but the VegaVisual keeps its own highlight until it's clicked - that chart owns it. If you take clicks yourself with `onSelectRows` instead, an
+empty list means the selection was CLEARED: set your state from exactly what it gives you and never toggle it again.
+Anything saved against a mark - a note, a flag - is keyed the same way, never by `__rowIdx__`.
+
+More the page gets from the same filters, each one line:
+- A link that opens the page as it was: `useBicUrlState()` in the page component (after its `useBicFilter` /
+  `useBicControls` calls) keeps every filter and every chart's controls in `?view=`. `useBicView()` gives `save()` /
+  `restore(view)` for a saved view of your own (a user's favourite), and `token()` for a link.
+- Linked hover: `useBicFilter("CountryIso3", { hover: true })` - hovering a mark lights the same key's marks on every
+  chart bound to that filter (a glow, never a selection).
+- A filter that narrows a query to nothing: `<BicChartPanel ... onClearFilters={country.clear}>` says so with a Clear,
+  instead of an empty chart. A chart's own empty message: `emptyText` on its component.
+- While building: `<BicDevtools />` shows every filter, its keys, why it last changed, and each chart's controls.
 
 **Notes (or flags) on marks, end to end.** People leave a note on a country, a route, a product, and see
 it on that mark: the notes live in Rayfin's data service, and the badge is the chart's `annotations`.
@@ -639,138 +709,76 @@ Check with `npx tsc -b`; a bare `tsc --noEmit` reports TS6305 until the `rayfin/
 TS2345 names two copies of `rayfin-auth`, something installed only some Rayfin packages: run
 `setup_fabric_app` again.
 
-*c. The entity, keyed by the model's key - never by a row position.* `rayfin/data/MarkNote.ts`, then
-register it in `rayfin/data/schema.ts` (`export type AppSchema = { MarkNote: MarkNote };`):
-
-```ts
-import { entity, authenticated, uuid, text, date } from '@microsoft/rayfin-core';
-
-@entity()
-@authenticated(['read', 'create'])
-export class MarkNote {
-  @uuid() id!: string;
-  @text({ max: 64 }) chart!: string;                       // which chart: "country-map", "lanes"
-  @text({ max: 128 }) markKey!: string;                    // the mark's model key (CountryCode)
-  @text({ max: 128, optional: true }) markKeyTo?: string;  // a route's other end; empty for one mark
-  @text({ max: 2000 }) body!: string;
-  @text({ max: 320 }) author!: string;
-  @date() createdAt!: Date;
-}
-```
+*c. The files: `setup_fabric_app` with `features: ["notes"]`.* With the data service on, it writes them finished and
+never rewrites them:
+- `rayfin/data/MarkNote.ts`, registered in `rayfin/data/schema.ts` - keyed by the mark's model key, never a row
+  position: `chart`, `markKey`, `markKeyTo` (a route's other end), `body`, `author`, `createdAt`. Every entity it
+  writes has an explicit permission decorator and a `max` on every `@text` (MSSQL gets `NVARCHAR(MAX)` without one,
+  which can break the deployed GraphQL schema).
+- `src/lib/bic-notes.ts`: `useMarkNotes(author)` - every note (paged with `.executePaginated()`: one query returns at
+  most 100 and doesn't say there are more), an `error` when they can't load, and `add(chart, key, body)`, which saves
+  with `.create(` and reloads, and REJECTS when the save fails. The author is the signed-in user:
+  `useAuth().session?.user?.email`.
+- `src/components/bic-notes-dialog.tsx`: `NotesDialog`, over the page through `createPortal`, never inside the
+  chart's card (a card has a fixed height and `overflow-hidden`, and clips it). The reader's text is cleared only once
+  the save succeeds; a failure is shown with the text kept.
+
+*d. Badges on the marks: pass `annotations`, never measure the chart.* The host draws each badge on its key's mark
+after every render and keeps it there through filters, re-queries and zooms; it never reads a row position. A route is
+keyed by BOTH of its ends with `where` - no key column to add, no query to change and no chart to regenerate:
 
-Give every entity an explicit permission decorator (without one, any signed-in user gets every
-action), and every `@text` a `max` (without it MSSQL gets `NVARCHAR(MAX)` columns, which can break
-the deployed GraphQL schema). Use `.js` extensions on relative imports between entity files.
-
-*d. Read every note, write one.* `.execute()` returns one page (100 rows) and doesn't say there are
-more, so page through:
-
-```ts
-// src/lib/mark-notes.ts
-import type { MarkAnnotation } from "@bicharts/chart-host";
-import { getRayfinClient } from "@/lib/rayfin-client";
-import type { MarkNote } from "../../rayfin/data/MarkNote";
-
-const FIELDS = ["id", "chart", "markKey", "markKeyTo", "body", "author", "createdAt"] as const;
-
-export async function loadMarkNotes(): Promise<MarkNote[]> {   // newest first
-  const all: MarkNote[] = [];
-  let after: string | undefined;
-  do {
-    const q = getRayfinClient().data.MarkNote.select([...FIELDS]).orderBy({ createdAt: "desc" }).first(100);
-    const page = await (after ? q.after(after) : q).executePaginated();
-    all.push(...page.items);
-    after = page.hasNextPage ? page.endCursor ?? undefined : undefined;
-  } while (after);
-  return all;
-}
+```tsx
+import { noteBadges, notesFor, badgeKey } from "@bicharts/chart-host/react";
 
-export function addMarkNote(n: Pick<MarkNote, "chart" | "markKey" | "markKeyTo" | "body">, author: string) {
-  return getRayfinClient().data.MarkNote.create({ ...n, author, createdAt: new Date() });
-}
-```
+import { useAuth } from "@/hooks/auth.context";
 
-In a hook, load inside the effect - `loadMarkNotes().then(all => { if (live) setNotes(all); })` with a
-`live` flag the cleanup clears; the template's lint rejects an effect that calls a state-setting
-function directly. The author is the signed-in user: `useAuth().session?.user?.email`.
-
-*e. Badges on the marks: pass `annotations`, never measure the chart.* The host draws each badge on
-its key's mark after every render and keeps it there through filters, re-queries and zooms; it never
-reads a row position. One key column is `column`/`value`. A route is keyed by BOTH of its ends with
-`where` - no key column to add, no query to change and no chart to regenerate:
-
-```ts
-/** One badge per mark: a single key column, or a route's two ends. */
-export function noteBadges(notes: MarkNote[], chart: string, key: [string] | [string, string]): MarkAnnotation[] {
-  const byMark = new Map<string, MarkNote[]>();
-  for (const n of notes) {
-    if (n.chart !== chart) continue;
-    const id = n.markKeyTo ? `${n.markKey}|${n.markKeyTo}` : n.markKey;
-    byMark.set(id, [...(byMark.get(id) ?? []), n]);
-  }
-  return [...byMark].map(([id, list]) => ({
-    id, label: String(list.length), title: list[0].body,
-    ...(key.length === 2
-      ? { where: { [key[0]]: list[0].markKey, [key[1]]: list[0].markKeyTo ?? "" } }
-      : { column: key[0], value: list[0].markKey }),
-  }));
-}
-```
+const { notes, add } = useMarkNotes(useAuth().session?.user?.email);
+<BivariateWorldChoroplethChart table={table} {...size} options={options} selects={country}
+  annotations={noteBadges(notes, { chart: "occupancy-map", columns: "CountryIso3" })}
+  onAnnotationClick={a => setOpen({ chart: "occupancy-map", columns: "CountryIso3", key: badgeKey(a) })} />
+// a route by both ends: noteBadges(notes, { chart: "routes", columns: ["OriginCode", "DestinationCode"] })
+// gives each route { where: { OriginCode: "ESP", DestinationCode: "PRT" }, label, title }
 
-```tsx
-<BivariateWorldChoroplethChart table={table} {...size} options={options}
-  annotations={noteBadges(notes, "country-map", ["CountryCode"])}
-  onAnnotationClick={a => setOpenMark(a.id ?? null)} />
-// a route by both ends: annotations={noteBadges(notes, "lanes", ["OriginCountryCode", "DestinationCountryCode"])},
-// one badge per route, each { where: { OriginCountryCode: n.origin, DestinationCountryCode: n.dest }, label, title }
+{open && <NotesDialog title={country.textOf(open.key, countryRows)} onClose={() => setOpen(null)}
+  notes={notesFor(notes, open.key, { chart: open.chart, columns: open.columns })}
+  onAdd={body => add(open.chart, open.key, body)} />}
+// open = { chart, columns, key }: keep the chart's key columns with it - a route's notes need both ends.
 ```
 
-Don't read `data-row-idx` or bounding boxes to place anything: that breaks on the next redraw, and
-this does it for you.
+Open a mark's notes from `onAnnotationClick` (`badgeKey(a)` is its key), and its first note from your own "Add a
+note" action on the selected mark - `country.keys[0]` is its key, `country.text` its name. Don't read `data-row-idx`
+or bounding boxes to place anything: that breaks on the next redraw, and this does it for you.
 
-*f. Open the notes over the page, never inside the chart's card.* Open them from `onAnnotationClick`
-for a mark that has notes, and for a mark's first note from your own "Add a note" action on the
-selected mark (`onSelectRows` gives you its key). Show them in a dialog, drawer or popover that
-overlays the page through a portal: a chart's card has a fixed height and `overflow-hidden`, so a
-panel inside it is clipped.
+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.
 
-```tsx
-import { useState } from "react";
-import { createPortal } from "react-dom";
-
-export function NotesDialog({ title, notes, onAdd, onClose }: {
-  title: string; notes: MarkNote[]; onAdd: (body: string) => void; onClose: () => void;
-}) {
-  const [draft, setDraft] = useState("");
-  return createPortal(
-    <div onClick={onClose} style={{ position: "fixed", inset: 0, zIndex: 1000, display: "grid",
-      placeItems: "center", background: "rgb(0 0 0 / 0.35)" }}>
-      <div role="dialog" aria-modal="true" aria-label={title} onClick={e => e.stopPropagation()}
-        style={{ width: "min(480px, 92vw)", maxHeight: "80vh", overflow: "auto", padding: 16,
-          borderRadius: 8, background: "Canvas", color: "CanvasText" }}>
-        <h2>{title}</h2>
-        <ul>{notes.map(n => <li key={n.id}>{n.body} - {n.author}, {new Date(n.createdAt).toLocaleString()}</li>)}</ul>
-        <textarea value={draft} onChange={e => setDraft(e.target.value)} maxLength={2000} />
-        <button disabled={!draft.trim()} onClick={() => { onAdd(draft.trim()); setDraft(""); }}>Add note</button>
-        <button onClick={onClose}>Close</button>
-      </div>
-    </div>,
-    document.body);
-}
-```
+Don't stand up a backend to test notes; the deploy creates the tables. Finish with `npx tsc -b` and the tests, and say the notes go live on deploy.
 
-Style it with the app's own tokens. The table and the permissions are created on the next
-`npx rayfin up`, and every later `rayfin up` applies entity changes.
+**7. A chart's own controls are page state: `useBicControls`.** A What-if chart's sliders (a rate, a horizon) are drawn
+inside the chart - build no slider beside it. Give the chart `controls` and read them on the page:
 
-Don't stand up a backend to test notes; the deploy creates the tables. Finish with `npx tsc -b` and the tests, and say the notes go live on deploy.
+```tsx
+import { useBicControls } from "@bicharts/chart-host/react";
+import { ScenariosPanel } from "@/components/bic-scenarios-panel";   // setup_fabric_app features: ["scenarios"]
+
+const scenario = useBicControls();
+<WhatIfProjectionChart table={table} {...size} options={options} controls={scenario} />
+<ScenariosPanel chart="bookings-forecast" controls={scenario} author={useAuth().session?.user?.email} />
+```
 
-**7. A reader's choice inside a chart is view state.** A what-if chart's rate and horizon are its
-own controls, reported through `viewState` on `<BicChart>` (`uiState` / `setUiState` in the
-integration contract). To save a named scenario, store that - don't rebuild the slider beside it.
+`scenario.values` holds every slider's value from the first draw - no slider has to move before a scenario can be
+saved - and `scenario.summary` is the chart's own label and readout for each ("price change per month +2.0% ·
+horizon 12 months"), so a saved scenario shows the unit the chart shows. `scenario.set(saved)` puts one back; `scenario.reset()`
+returns to the chart's defaults. Don't read `uiState.knobs` or the chart's source, and never save a default you made
+up. `features: ["scenarios"]` writes the `SavedScenario` entity, `useSavedScenarios` and `ScenariosPanel` (save under a
+name, list, apply, and which one is applied now - `applied`, the saved scenario whose values the chart shows; a failed
+save keeps what was typed).
 
-**8. What stays the template's job:** sign-in, the query hooks, the app's database (Rayfin's data
-service - the notes recipe above), `VisualContainer` headers, deployment. The chart is a function you
-render inside them.
+**8. What stays the template's job - this is additive, never a replacement:** sign-in, the query hooks
+(`useSemanticModelQuery`; a page filter feeds it through `filterQuery`), the theme (`useCssTheme`, which
+`bic-chart-options.ts` builds on), the app's database (Rayfin's data service), `VisualContainer` headers, the template's
+own `VegaVisual` charts and `DataGrid` (which join a page filter through `fromVegaInteraction`), its skills, and
+deployment. The chart is a function you render inside them.
 
 **9. Check every chart, then deploy.** Check every chart locally with this server's `check_chart` tool,
 at the size the panel will give it - by default it reads the chart's `minChartWidth` and `minChartHeight`
@@ -778,7 +786,11 @@ off its `BicChartPanel`, so pass no size unless you mean another one. A `WARNING
 label cut off at that size: deal with it before you call the chart done. The reply says whether more room fixes it.
 Never edit the generated chart code by hand: if something's wrong with a generated chart, regenerate it
 (`generate_chart` with a prompt describing the fix) or report it.
-You don't need to deploy to check a chart. Then `npx tsc -b` and the tests. Deploying (`npx rayfin up`), on Rayfin 1.36.1:
+You don't need to deploy to check a chart. The template's `validate:visual` checks `VegaVisual` factories; a
+RegiaBI chart's check is `check_chart` - don't list it there. And `check_chart` checks the chart, not the app: the
+template's app-validation in the portal embed still applies. Then `npx tsc -b` and the tests. To test the page's behaviour,
+`@bicharts/chart-host/testing` has a reader's gestures - `clickMark`, `clickEmpty`, `selectedRows` - for the checks
+worth keeping: a second click on a mark clears its filter, and a page Clear clears the chart's marks. Deploying (`npx rayfin up`), on Rayfin 1.36.1:
 - Signed in? `npx rayfin login status` (a subcommand, not a `--status` flag); `npx rayfin login` if not.
 - Name the workspace: `npx rayfin up -w "<workspace>"`. Left out, it deploys to My Workspace.
 - The Fabric item is named by `id:` in `rayfin/rayfin.yml`, not `name:`. Two projects with the same