@bicharts/chart-mcp 0.6.52 → 0.6.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-mcp",
-  "version": "0.6.52",
+  "version": "0.6.55",
   "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). Requires a BIC trial or paid account.",
   "keywords": [
     "mcp",
@@ -41,17 +41,21 @@
     "prestart": "node build.mjs",
     "start": "node dist/index.mjs"
   },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "papaparse": "^5.4.1",
-    "zod": "^3.23.0"
-  },
+  "// 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.52",
     "@bicharts/shape-core": "^0.6.52",
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "@types/node": "^20.0.0",
     "@types/papaparse": "^5.3.14",
+    "d3": "^7.9.0",
+    "d3-hexbin": "^0.2.2",
+    "d3-sankey": "^0.12.3",
+    "d3-voronoi-treemap": "^1.1.2",
     "esbuild": "^0.28.1",
-    "typescript": "^5.4.0"
+    "happy-dom": "^20.14.5",
+    "papaparse": "^5.4.1",
+    "typescript": "^5.4.0",
+    "zod": "^3.23.0"
   }
 }

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

@@ -59,7 +59,7 @@ on the same picture, not a looser one.
 | 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 |
-| Gauge | 1 continuous, a bounded scale | needs 140x140 px | D3 | One value against a ceiling the data states - a percentage, a rate, or a measure that has a target |
+| Gauge | 1 continuous, a bounded scale | needs 140x140 px | D3 | A value against a ceiling the data states - a percentage, a rate, or a measure that has a target - overall or one dial per category; a constant value is a valid reading |
 | Grouped bar chart | 2 categorical, 1 continuous | needs 700x480 px | D3, Matplotlib, Plotly, Seaborn | Requires one categorical, one subcategory, and one numeric variable |
 | Heatmap | 2 categorical, 1 continuous | <=50 categories, needs 460x340 px | D3, Matplotlib, Plotly, Seaborn | Requires two categorical or ordinal fields for the rows and columns, and one measure for the cell colour |
 | Hexbin plot | 2 continuous | needs 280x280 px | D3, Matplotlib, Plotly, Seaborn | Requires two continuous variables |
@@ -71,7 +71,7 @@ on the same picture, not a looser one.
 | 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 |
-| Linear gauge | 1 continuous, a bounded scale | needs 180x50 px | D3 | One value against a ceiling the data states, in a short wide tile - percent complete, utilisation, progress to a target |
+| Linear gauge | 1 continuous, a bounded scale | needs 180x50 px | D3 | A value against a ceiling the data states, overall or one track per category, in a short wide tile - percent complete, utilisation, progress to a target; a constant value is a valid reading |
 | Lollipop chart | 1 categorical, 1 continuous | <=50 categories, needs 600x420 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 |
@@ -87,12 +87,13 @@ on the same picture, not a looser one.
 | 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 |
 | Polar plot | 1 continuous | needs 299x283 px | D3, Matplotlib, Plotly | Requires angle and radius (two continuous variables) |
-| Progress ring | 1 continuous, a bounded scale | needs 160x160 px | D3 | One value against a ceiling the data states, in a small or square tile - percent complete, attainment, utilisation |
+| 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 |
 | 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 |
 | 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 |
@@ -108,7 +109,7 @@ on the same picture, not a looser one.
 | Sunburst chart | 2 categorical, 1 continuous | needs 400x300 px | D3, Matplotlib, Plotly | Requires hierarchical categorical data |
 | Tabular 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 |
-| Thermometer | 1 continuous, a bounded scale | needs 90x220 px | D3 | One value against a ceiling the data states, in a tall narrow tile - a sidebar rail or a column of KPIs down a page edge |
+| 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 |
 | Treemap | 1 categorical, 1 continuous | needs 240x220 px | D3, Matplotlib, Plotly | Requires hierarchical categorical data with values |

package/skills/bic-charts/SKILL.md

@@ -21,6 +21,16 @@ Skip this if you already have a table. If you are holding a semantic model, a wa
 a database, **you** pick the fields — the tools take a table, not a model, and they cannot see
 what you can. Three decisions, and the third is the one that goes wrong.
 
+**Asked which charts suit the model itself** ("good chart types for this dataset", "what could we
+chart here")? Over a semantic model in a Fabric App, `suggest_charts` answers in one call: it reads
+the model's tables, measures and relationships, finds its natural views (measures by place, flows
+between places, measures over time, measures by category), queries each at its grain, keeps the
+measures that vary there and asks the eligibility engine what fits each. Answer from its reply -
+the counts in it are the model's own - and build the one the person picks from the rows it saved
+(`.bic/data/<view>.csv`, the DAX beside it). Pass `views` (`columns` as `Table[Column]`, `measures`
+by name, or your own `dax`) to ask about other groupings. Elsewhere, pull each candidate grouping
+and ask `list_eligible_charts` about each.
+
 **Fields and filters** follow from the question. *"All loans over the last 6 months, highlighting
 those which defaulted, paying attention to credit score"* wants `LoanId`, `Defaulted`,
 `CreditScore`, filtered to six months.
@@ -464,8 +474,14 @@ build.
 `src/lib/bic-chart-options.ts` (`useBicChartOptions()`: the app's Fabric theme - palette, foreground,
 background - as chart options, so charts follow light and dark) and `src/components/bic-chart-panel.tsx`
 (`<BicChartPanel result={useSemanticModelQuery(...)}>`: a box that measures itself and shows the query's
-loading, error and empty states), and ignores `.bic/`. It never overwrites a file, and its reply ends with a
-worked example.
+loading, error and empty states), and ignores `.bic/`. It also puts every `@microsoft/rayfin-*` package on one version -
+npm's latest, the release `rayfin init` installs, so run it before `rayfin init` and init has nothing left to split
+(`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
+`.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.
 
 **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
@@ -484,7 +500,7 @@ simply offered other charts. Save the result to a file and pass `csv_path`, or p
 `RevenuePerCapita`, 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.
+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
@@ -568,40 +584,200 @@ function CountryMap({ table, onPick }) {          // table = the live query resu
 - **`<BicChartGroup destination>` needs `@bicharts/chart-host` 0.6.50 or later.** Before it, a flow
   map's far end is not built.
 
+**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.
+- 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
+  `min-height: auto` lets it grow past its card, and the card's `overflow-hidden` slices off the rest.
+
 **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).
 
-**Notes (or flags) shown ON a mark: pass `annotations`, never measure the chart.** The host draws the
-badge on the key's mark after every render and keeps it there through filters, re-queries and zooms;
-it never reads a row position. From a notes table keyed by the model's key:
+**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`.
+This recipe was checked against Rayfin's own docs for Rayfin 1.36.1 (a preview), the version
+`setup_fabric_app` installs as this is written, and on that version it IS the version-matched source:
+follow it as written, and read Rayfin's docs (`node_modules/@microsoft/rayfin-guide/assets/docs/data/`)
+only for what it doesn't cover. `setup_fabric_app`'s reply names the version it installed; where that
+differs from 1.36.1, Rayfin's docs win.
 
-```tsx
-<BivariateWorldChoroplethChart table={table} {...size} options={options}
-  annotations={notes.map(n => ({ column: "CountryCode", value: n.countryCode,
-                                 label: String(n.count), title: n.latestText }))}
-  onAnnotationClick={a => openNotes(a.value)} />
+*a. Turn the data service on.* The data app template ships it off. Run `setup_fabric_app` first (it puts every `@microsoft/rayfin-*` package on one version:
+npm's latest, the release `rayfin init` installs), then:
+
+```bash
+npx rayfin init --services auth,data --auth-methods fabric --dialect mssql --overwrite --project-name <id from rayfin/rayfin.yml> .
+```
+
+Each flag is needed: without `--overwrite` it prints "Initialization cancelled" and exits 0 with no
+reason; without `--project-name` (pass the `id:` already in `rayfin/rayfin.yml`, so nothing is renamed)
+it stops with "--project-name is required in non-interactive mode". It rewrites `rayfin/rayfin.yml`
+and `.gitignore`, so `git diff` both and put back what's yours (on 1.36.1 it dropped the template's
+`src/fabric.generated.ts` line from `.gitignore`). It writes `rayfin/tsconfig.json` - keep its
+`outDir`, `.temp/compiled`, which is where the deploy reads the entities from - and no entities.
+
+*b. Make it type-check.* Three edits, each needed on the data app template:
+- `rayfin/tsconfig.json`, in `compilerOptions`: `"tsBuildInfoFile": ".temp/tsconfig.tsbuildinfo"` and
+  `"allowImportingTsExtensions": false` (it inherits both from the root: TS6377 and TS5096 otherwise).
+- the root `tsconfig.json`: `"references": [{ "path": "./rayfin" }]`.
+- type the client with your schema: `RayfinClient<AppSchema>` in `src/lib/rayfin-client.ts`
+  (`import type { AppSchema } from "../../rayfin/data/schema";`) and in the constructor of
+  `src/services/rayfin-auth.service.ts` (TS2345 otherwise).
+
+Check with `npx tsc -b`; a bare `tsc --noEmit` reports TS6305 until the `rayfin/` project is built. If a
+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;
+}
+```
+
+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;
+}
+
+export function addMarkNote(n: Pick<MarkNote, "chart" | "markKey" | "markKeyTo" | "body">, author: string) {
+  return getRayfinClient().data.MarkNote.create({ ...n, author, createdAt: new Date() });
+}
 ```
 
-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:
+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 }),
+  }));
+}
+```
 
 ```tsx
-annotations={laneNotes.map(n => ({ where: { OriginCountryCode: n.origin, DestinationCountryCode: n.dest },
-                                   label: String(n.count), title: n.latestText }))}
+<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 }
 ```
 
 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.
+
+```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);
+}
+```
+
+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.
+
+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.
+
 **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.
 
-**8. What stays the template's job:** sign-in, the query hooks, the app's database, `VisualContainer`
-headers, deployment (`npx rayfin up`). The chart is a function you render inside them.
+**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.
+
+**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`
+off its `BicChartPanel`, so pass no size unless you mean another one. A `WARNING` line in its reply is a
+label likely cut off at that size: deal with it before you call the chart done.
+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:
+- 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
+  `id:` in one workspace deploy into one item: give each its own `id:`, or deploy with
+  `--item-name <unique-name>`. Pass `--yes` to reuse an existing item only when you know it's yours.
+- Deleted the app outside Rayfin? `rayfin/.deployments.json` still names the deleted item, so the next
+  `rayfin up` fails with 404 Not Found. Move that file aside and deploy again.
 
 ## 4. Things that will otherwise cost you time