@metabase/cli 0.5.1 → 0.5.3

package/skill-data/data-app-data/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: data-app-data
+description: Give a Metabase data app its data — questions in the app's collection over the Library's published tables and metrics, the typed `src/metabase.ts` that `mb data-app typed-schema` generates, and the `useMetabaseQuery` and `useMetabaseQueryObject` hooks that run them, with runtime filter clauses, sorting and aggregation. Triggers — "show revenue by month in my data app", "list customers in the app", "add a KPI", "a chart of orders by category", "regenerate metabase.ts". Creating and publishing the app is `data-app`; filter controls are `data-app-filters`; writes are `data-app-actions`; chart choice and sizing are `data-app-ui`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+requires: [dataApps]
+---
+
+# Data in a data app
+
+A data app runs only the questions and actions in **the app's collection** (`data-app`, _Create the app_); its viewers can read nothing else. So every piece of data starts there:
+
+1. Create a question (below) or an action (`data-app-actions`) in the app's collection.
+2. Regenerate `src/metabase.ts`, the typed list of everything in the collection.
+3. Pass `queries.<name>` or `actions.<name>` from it to a hook.
+
+## Sources: the semantic layer only
+
+An app reads only what the user curated in the Library. These are hard rules:
+
+- **Tables published to the Library**, and nothing else: `mb table list --published-only --json`. That covers the question's source table, every join, and every table reached through a foreign key column.
+- **Metrics in the Library's Metrics collection** (its id is in `mb library get`; list it with `mb collection items <id> --json`), and the segments and measures of published tables (`mb segment list`, `mb measure list`). Prefer one that matches the concept over rebuilding it with filters and thresholds of your own.
+- **Other questions in the app's collection**, as a source. Never a question, model or metric from anywhere else.
+- **MBQL only**, never native SQL.
+
+When the app needs a table or metric the Library lacks, stop: name what's missing and ask the user to publish the table or move the metric into the Library. Don't publish it yourself unless the user says to, and never work around the gap with an unpublished table, a copy of the data, or SQL.
+
+## Questions
+
+Write each question's query in MBQL (the `mbql` skill), finding ids with `mb table list --published-only --term <name>` and `mb table get <id> --include fields --json`. Write the `dataset_query` object to `query.json`, dry-run it, then create the question in the app's collection:
+
+```bash
+mb query --dry-run --file query.json
+mb card create --json --body '{
+  "name": "Revenue by month",
+  "type": "question",
+  "display": "line",
+  "collection_id": 42,
+  "visualization_settings": {},
+  "dataset_query": { … }
+}'
+mb card query <id> --json --max-bytes 0 | jq '{row_count, first: .data.rows[0]}'
+```
+
+Plan the questions from what the app shows and picks from — each chart, KPI, table and filter option list needs one, and several panels may share one. Each takes one of two shapes:
+
+- **Aggregated**, when the breakdown is fixed: revenue by month, top products. Runtime clauses can then name only the columns it returns, its breakouts and aggregations.
+- **Rows**, when a runtime filter targets a column an aggregation would drop — revenue by month, filtered by product category. The question returns the raw columns (`CREATED_AT`, `TOTAL`, `CATEGORY`), and the hook filters and aggregates them at runtime (_Runtime clauses_).
+
+Also:
+
+- A question filtered at runtime has no `limit` of its own: it would apply before the filters. Put the limit in the hook. A question nothing filters, such as "the 20 latest reviews", keeps its sort and limit.
+- The name becomes the key in `queries`, camelCased: `Revenue by month` → `queries.revenueByMonth`.
+- `display` and `visualization_settings` show only in Metabase; the app picks its own chart type.
+- Nothing in the app's collection is archived, public or embedded. To drop a question, move it out (`mb card update <id> --body '{"collection_id":<other>}'`), then archive it.
+
+## `src/metabase.ts`
+
+```bash
+mb data-app typed-schema <slug> --out src/metabase.ts
+```
+
+Run it after **every** change to the app's collection, then `npm run typecheck`, which catches code still using a renamed or removed column. Never edit the file. It names every question and action by entity ID, so it works unchanged on every instance the app is synced to.
+
+```ts
+export const queries = {
+  revenueByMonth: defineQuery({
+    source: {
+      type: "card",
+      entityId: "…",
+      name: "Revenue by month",
+      columns: [
+        { type: "column", name: "CREATED_AT", displayName: "Created At: Month", jsType: "Date", semanticType: "type/CreationTimestamp" },
+        { type: "column", name: "sum", displayName: "Sum of Total", jsType: "number", semanticType: "type/Currency" },
+      ],
+    },
+  }),
+};
+export const actions = { setOrderNote: defineAction({ action: { id: "…", parameters: [ … ] } }) };
+```
+
+A column's `name` keys the rows and names the column in runtime clauses. Take it from this file, never from SQL:
+
+- A column reached through a foreign key keeps its own name (`CATEGORY`, not `PRODUCTS__via__PRODUCT_ID__CATEGORY`), and a named aggregation keeps its name.
+- A foreign key that Metabase displays as a name returns that name as an extra column: `USER_ID` comes with a `NAME` column whose `displayName` is "User ID". Show `NAME`; filter by `USER_ID`.
+- A `Date` column's values arrive as ISO strings.
+
+## Rows: `useMetabaseQuery`
+
+```tsx
+import { useMetabaseQuery } from "@metabase/embedding-sdk-react/data-app";
+import { queries } from "../metabase";
+
+const { data, error, refetch } = useMetabaseQuery(queries.revenueByMonth);
+const rows = data?.rows ?? []; // row.CREATED_AT, row.sum, typed from jsType
+```
+
+- Rows are objects keyed by column `name`. Never index them by position or cast them, and guard `null` values.
+- `data` is `null` until the first answer, and stays `null` while the query is held back with `enabled: false` — show the before-a-choice state then. Otherwise `data === null && !error` is loading, and `data.rows.length === 0` is empty.
+- `error` is `unknown`: render `error instanceof Error ? error.message : String(error)` in the panel.
+- Call each hook once, in the highest component that needs the data, and pass the result down. Never call a hook in a loop or a condition.
+
+## Charts: `useMetabaseQueryObject`
+
+A chart, KPI or table Metabase can draw renders as an SDK question:
+
+```tsx
+import { StaticQuestion, type MetabaseCard } from "@metabase/embedding-sdk-react";
+import { useMetabaseQueryObject } from "@metabase/embedding-sdk-react/data-app";
+import { useMemo } from "react";
+
+const { query, isLoading, error } = useMetabaseQueryObject(queries.revenueByMonth);
+const card = useMemo(() => ({ query, visualization: "line" }) satisfies MetabaseCard, [query]);
+
+// PanelError and Spinner are the app's own components
+if (error) return <PanelError error={error} />;
+if (isLoading || !query) return <Spinner />;
+return <StaticQuestion card={card} height={360} />;
+```
+
+- Always pass `visualization`: the question's own `display` doesn't reach the app, and without one Metabase picks a default, often a table. Which chart, its settings and its size: `data-app-ui`.
+- Build `card` with `useMemo` keyed on `query`: a new object re-runs the question.
+- Render `error` wherever this hook is used: reading only `query` makes a failed question look like endless loading.
+
+## Runtime clauses
+
+Both hooks take a second argument: one object with the clauses the UI changes, and `enabled`. They run on top of the question and name its columns:
+
+```tsx
+import { aggregations, filter, orderBy } from "@metabase/embedding-sdk-react/data-app";
+
+const [start, end] = range; // from DateRangePopover (data-app-filters)
+const { query } = useMetabaseQueryObject(queries.orderRows, {
+  filters:
+    start && end ? [filter({ type: "column", name: "CREATED_AT" }, "between", [start, end])] : [],
+  aggregations: [aggregations.sum({ type: "column", name: "TOTAL" }, { name: "revenue" })],
+  breakouts: [{ type: "column", name: "CREATED_AT", unit: "month" }],
+  orderBys: [orderBy({ type: "column", name: "CREATED_AT" }, "asc")],
+});
+```
+
+- A column is `{ type: "column", name }` with a `name` from `src/metabase.ts`; a wrong name, or an operator its type doesn't take, fails to compile. A date breakout takes a `unit` (`day`, `week`, `month`, `quarter`, `year`).
+
+  | Column type | Operators                                                                                                             |
+  | ----------- | --------------------------------------------------------------------------------------------------------------------- |
+  | string      | `=`, `!=`, `contains`, `does-not-contain`, `starts-with`, `ends-with`, `is-empty`, `not-empty`, `is-null`, `not-null` |
+  | number      | `=`, `!=`, `>`, `>=`, `<`, `<=`, `between`, `is-null`, `not-null`                                                     |
+  | date        | `=`, `!=`, `>`, `>=`, `<`, `<=`, `between`, `time-interval`, `is-null`, `not-null`                                    |
+  | boolean     | `=`, `is-null`, `not-null`                                                                                            |
+
+- `filter(...)` takes one value: `filter(col, "=", [a, b])` compiles but is not an IN filter, and several filters AND together. So a filter picks one value or All; for a multi-select, ask the user whether a single choice will do.
+- Text operators are case-sensitive, with no option to change it: say so in the search box's placeholder.
+- `time-interval` (`[-30, "day"]`, `[0, "year"]` for this year) is relative to when the query runs: a fixed window belongs in the question, not the hook.
+- On a rows question, aggregate with any of `aggregations.count`, `sum`, `avg`, `median`, `min`, `max`, `distinct`, naming each result (`{ name: "revenue" }`) to order or read it by — two unnamed results of one operator collide, and generated names such as `sum_2` aren't stable. On an aggregated question, re-aggregate only sums and counts, which add up.
+- A sort the user picks: map each choice to a column explicitly (`{ revenue: "revenue", orders: "order_count" }`) rather than passing the user's value through.
+- `enabled: false` holds the query back, for example until the user picks an item.
+- Write the arrays inline (spreads are fine): the hooks compare by content, so a new array per render doesn't refetch. A clauses object built outside the call needs `as const`, or `aggregations` loses the tuple type `breakouts` need; a shared `ReturnType<typeof filter>[]` built with `push` breaks the operator types the same way.
+
+The controls that feed these clauses are `data-app-filters`. When the data is in place, build and publish (`data-app`, _Build and publish_).

package/skill-data/data-app-filters/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: data-app-filters
+description: Build the filter controls of a Metabase data app — the filter contract, which cards a filter reaches, All by default, options from their own question, a searchable combobox for entities, date presets, `DateRangePopover` and `DateRangeCalendar` with labels from `useDateFormatter`, and a single-date picker. Triggers — "add a filter to the app", "filter the chart by date", "a date range picker", "filter by customer", "a dropdown of categories", "the filter doesn't change the chart", "the date shows the previous day". The query side — runtime clauses and their limits — is in `data-app-data`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+requires: [dataApps]
+---
+
+# Filter controls in a data app
+
+A filter is an ordinary React control whose state becomes `filter(...)` clauses in a hook's second argument, on a column the question returns (`data-app-data`, _Runtime clauses_). This skill covers the controls; "panel" below means a chart, KPI or table on the page.
+
+## Write the contract first
+
+Before any control, write one row per filter: the question that gives its options, the raw value `filter(...)` receives, the panels whose question returns that column, and the panels whose question doesn't.
+
+| Filter    | Options question           | Raw value    | Panels                 | Not these      |
+| --------- | -------------------------- | ------------ | ---------------------- | -------------- |
+| Franchise | franchises, by id and name | franchise id | orders, revenue, stock | —              |
+| Plan      | orders broken out by plan  | plan text    | orders                 | revenue, stock |
+
+- A filter in the page's global bar changes every panel that can take it. One that can't reach a panel is scoped to its section, visibly, or left out. A KPI and its detail table about the same thing take the same filters, unless the UI says why not.
+- One date control per scope. Never a global date range beside a page-specific date where one of the two does nothing; a page whose cards use another date column gets one control for that column.
+- Build each panel's clauses from its own question's columns, inline at its hook call. Never reuse an array built for another question.
+
+## Values and options
+
+- Every filter starts at **All**. Keep it as `"all"` in state and send it as no clause (`[]`); treat `""`, `null` and `undefined` the same way. In a Yes/No/All filter, Yes and No each filter (`true`, `false`), and only All sends nothing.
+- Options come at runtime from their own question in the app's collection, broken out on the filtered column — never hardcoded unless the user gave a closed list. Dedupe them from its rows, and keep the label apart from the value.
+- Filter by a stable raw value (an id) and show its label; never filter by a display label when an id exists, and never feed free text into an exact-id filter.
+- All stays selectable while options load, come back empty or fail; don't disable the control. When fresh options no longer hold the selected value, reset to All:
+
+```tsx
+useEffect(() => {
+  if (selected !== "all" && !options.some((option) => option.value === selected)) {
+    setSelected("all");
+  }
+}, [options, selected]);
+```
+
+## Entities: a searchable combobox
+
+Any list whose options come from a question — an id shown as a name, a category, anything that can grow — is one searchable combobox, even while it's short. A `<select>` is only for a short closed list the user gave. Prefer the app's component library or a small established combobox package; hand-roll only a small one. Either way:
+
+- Click or focus opens the list at once, before any typing; search matches labels, not ids.
+- All is always an option, and picking an option stores its raw value.
+- The list is capped or scrolls, and looks like the app's other controls.
+- Don't close the list from the trigger's `onBlur` when the popover holds an auto-focused input — moving focus into it closes the list at once. Close on selection, Escape, or focus leaving the whole wrapper.
+
+## Date ranges
+
+A preset bar lists the durations, then All time, then Custom last — leave Custom out only if the user asked for fixed presets. Every option ends in the same `[start, end]` range (All time is `[null, null]`), so one `between` filter serves them all. Custom is `DateRangePopover` around your own trigger, or `DateRangeCalendar` inline, both from `@metabase/embedding-sdk-react/data-app`. No date-picker library and no `<input type="date">` for a range.
+
+```tsx
+import { DateRangePopover, filter, useDateFormatter } from "@metabase/embedding-sdk-react/data-app";
+
+const { formatDateRange } = useDateFormatter();
+const [range, setRange] = useState<[string | null, string | null]>([null, null]);
+const [start, end] = range;
+// at the hook: filters: start && end ? [filter({ type: "column", name: "CREATED_AT" }, "between", [start, end])] : []
+
+<DateRangePopover value={range} onChange={setRange}>
+  <button className="filter-button">{formatDateRange(range) || "Custom"}</button>
+</DateRangePopover>;
+```
+
+- Both ends are `YYYY-MM-DD` strings, the shape `filter(...)` takes. `onChange` fires on every click, so a half-picked range arrives as `[start, null]`: filter only once both ends are set, never with a sentinel date.
+- The child is the trigger: one element or a `forwardRef` component, since the popover attaches a ref and a click handler.
+- Label it with `formatDateRange(range)` (or `formatDate` for one end), which formats in the instance's locale; both take a dayjs `format`, and `formatDateRange` a `separator`. It returns `""` until the SDK loads. Never `new Date("YYYY-MM-DD")`: a date-only string parses as UTC and shows the previous day west of Greenwich.
+- The popover closes once both ends are picked (`closeOnSelect`); `opened` and `onOpenedChange` control it yourself. Also `defaultValue`, `minDate` and `maxDate` (`YYYY-MM-DD`), `numberOfColumns` (default 2) and `position` (default `bottom-start`). `DateRangeCalendar` takes the same value props plus `className` and `style`.
+
+A preset's range, from local dates — never `toISOString()`, which shifts the day:
+
+```ts
+const ymd = (d: Date) =>
+  `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+const lastMonths = (n: number): [string, string] => {
+  const end = new Date();
+  const start = new Date(end.getFullYear(), end.getMonth() - n, end.getDate());
+  return [ymd(start), ymd(end)];
+};
+```
+
+**A single date or a date-time** is the one case for a library: `npm install react-datepicker`, import `react-datepicker/dist/react-datepicker.css`, type the callback (`(date: Date | null) => …`), and convert with `ymd` above. Pass `null`, never `new Date("")`, for an empty value.
+
+## Check
+
+For every visible filter: All runs the unfiltered question; its options come from a question; each option changes every panel the contract says it reaches, and no other; a preset bar ends with Custom; and no scope has two date controls. Search the filter controls for `<select` and `type="date"` — an action form keeps its date inputs. Then build and publish (`data-app`, _Build and publish_).

package/skill-data/data-app-ui/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: data-app-ui
+description: Write a Metabase data app's UI — what the sandbox blocks and what replaces it, external APIs through `allowed_hosts`, layout and sizing, the SDK theme, a custom error state, the SDK components on offer, a Metabase chart versus a hand-drawn one and its visualization settings, pages with `DataAppRouter`, and what the app may show. Triggers — "change the layout", "theme the app", "add a page", "link between pages", "call an external API from the app", "the chart overflows", "invisible chart labels", "make it look like our brand". Creating and publishing is `data-app`; its data is `data-app-data`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+requires: [dataApps]
+---
+
+# A data app's UI
+
+Everything here runs inside the sandbox, the same in the dev preview as in Metabase; check each change in the preview and its diagnostics feed (`data-app`).
+
+## Source
+
+- Plain ESM and TSX. SDK components come from `@metabase/embedding-sdk-react`; the data hooks, routing, `copy`, `DateRangePopover`, `DateRangeCalendar` and `useDateFormatter` from `@metabase/embedding-sdk-react/data-app`. JSX needs no `import React`; import hooks and React types by name.
+- React, React DOM and both SDK entries come from the host. Never read SDK values off `globalThis`: the sandbox globals there are private.
+- The build is one self-contained file: CSS is inlined, `import logo from "./logo.png"` is a data URI, `import Icon from "./icon.svg?react"` a component (add `declare module "*.svg?react";` in a `.d.ts` under `src/` if the editor doesn't know it). Keep large binaries out. There's no `index.html` and no Vite plugin to add: solve it in `src/`.
+- Once the app grows: `src/App.tsx` for routing and composition, `pages/` one file per screen, `components/`, `hooks/`, `lib/` for pure helpers.
+
+## What the app shows
+
+- Only what Metabase returned, or deterministic transforms of it: no sample data, invented KPIs, trends, statuses, or claims such as "real-time" or "at risk" the data doesn't support. A section no question supports is left out.
+- Don't read a `rate`, `score`, `margin` or `percent` column as a percentage or threshold — no `%`, `* 100`, colors or stars — unless its `semanticType` in `src/metabase.ts`, or the user, says so.
+- Every panel has a loading state, its error, and an empty state for no rows — never an empty slot or a stale value.
+- Label with names, not ids; currency to two decimals, counts as integers; a `null` breakout is "Unknown". A trend needs several points: never a sparkline from one value. Cap long lists with a limit, pages or a scroll area.
+
+## What the sandbox blocks
+
+| Blocked                                                                                                    | Use instead                                                                               |
+| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `fetch` to Metabase or to any origin outside the app's `allowed_hosts`; `XMLHttpRequest`; `WebSocket`      | The data hooks for Metabase; _External APIs_ for anything else.                           |
+| `alert`, `confirm`, `prompt`                                                                               | A modal in your own tree.                                                                 |
+| `localStorage`, `sessionStorage`, `indexedDB`, `document.cookie`                                           | Nothing persists across reloads; persist through an action (`data-app-actions`).          |
+| `window.open`, `history.pushState`, `history.replaceState`                                                 | `useDataAppLocation().navigate`; `<a target="_blank" rel="noopener">` for external links. |
+| `navigator.clipboard`, `execCommand("copy")`                                                               | `await copy(text)` in a user event — write-only, there's no paste.                        |
+| `navigator.geolocation` and other device APIs                                                              | Nothing.                                                                                  |
+| Key, input, composition and clipboard listeners (`keydown`, `paste`, `input`, …) on `window` or `document` | A React handler (`onKeyDown`, `onPaste`, …) on your own element.                          |
+
+**External APIs.** A raw `fetch` reaches only the origins in the app's `allowed_hosts`, exact or with a `*.` subdomain wildcard: `mb data-app update <slug> --body '{"allowed_hosts":["https://api.example.com"]}'`, plus an `allowed_hosts:` list in `data_app.yaml` beside `package.json` for the preview, then restart `npm run dev`. Never list the Metabase URL. In Metabase the same list governs `<iframe src>` and native `<form action>` submits, and the target must allow framing; the preview blocks both. Use `<form onSubmit>` with `preventDefault`: a native submit navigates the app away.
+
+## Layout
+
+- The root element gets `minHeight: "100vh"` (plus `boxSizing: "border-box"` with padding) and the page background; never `height`. Regions that reach the bottom, such as a sidebar, go in a flex-column root with `flex: 1`. Check the emptiest screens — loading, empty, a lone KPI — since they render shortest.
+- SDK questions don't size to their parent: pass `height` and `width` to the component that draws (`StaticQuestion`, `InteractiveQuestion`, or `InteractiveQuestion.QuestionVisualization`) — the height actually left in its panel, or `height="100%"` in a fixed-height box. A KPI needs little: about `120` for a `scalar`, more for a `smartscalar`'s comparison or a `gauge`.
+- Don't wrap an SDK question in `overflow: hidden`, hover transforms or hover-driven layout shifts: its menus and tooltips need stable geometry.
+
+## Theme
+
+`src/theme.ts`, passed as `providerProps.theme`, is the only way to style SDK components, one theme for the whole app; it never styles your own UI (inline styles or CSS modules).
+
+| Key                                                    | Rule                                                                                                                                     |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `colors.brand`                                         | The app's accent.                                                                                                                        |
+| `colors["brand-hover"]`, `colors["brand-hover-light"]` | A light tint (`#EAF4FF` for a blue brand), never the saturated brand.                                                                    |
+| `colors.charts`                                        | All 8 slots, starting with `brand`, vivid and distinct — never pale tints, which can color labels. An empty slot keeps Metabase's color. |
+| `colors.background`, `colors["background-secondary"]`  | The color of the SDK component's own container: `white` inside a white card.                                                             |
+| `colors["text-primary"]`, `-secondary`, `-tertiary`    | Contrast with `background`; set them whenever you set it. Missing contrast is the "invisible chart labels" bug.                          |
+| `colors.positive`, `colors.negative`, `fontFamily`     | Up and down in trends and changes; the SDK's typeface. A `text-hover` must contrast with both brand-hover colors in open menus.          |
+
+**Error state.** A question that can't load shows Metabase's neutral error. To match the app, add an `errorComponent` to `providerProps` — it replaces the error of every SDK component, so keep the wording generic, render its `message` (a `ReactNode`) as it is, and use no data hooks in it:
+
+```tsx
+import type { SdkErrorComponentProps } from "@metabase/embedding-sdk-react";
+
+export function AppError({ message }: SdkErrorComponentProps) {
+  return <div style={{ padding: 16, color: "#6b7280" }}>{message}</div>;
+}
+// src/index.tsx: providerProps: { theme, errorComponent: AppError }
+```
+
+## SDK components
+
+| Import                                                                           | For                                                                   |
+| -------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `StaticQuestion`                                                                 | A chart, KPI or table without drill-through — the default.            |
+| `InteractiveQuestion`                                                            | One meant to be explored: drill-through, chart switching, the editor. |
+| `StaticDashboard`, `InteractiveDashboard`, `EditableDashboard`                   | A dashboard.                                                          |
+| `CreateQuestion`, `MetabotQuestion`, `CollectionBrowser`, `CreateDashboardModal` | Authoring flows, rarely in an app.                                    |
+
+## A Metabase chart or your own
+
+Ask "can Metabase draw this at all?", never "which looks closer to the design?" — and decide per element, not per page.
+
+- **Yes** — bar, line, area, combo, row, pie, scalar, smartscalar, gauge, progress, funnel, scatter, waterfall, boxplot, sankey, pivot, map, tables: render it with `useMetabaseQueryObject` and `StaticQuestion` (`data-app-data`). It keeps the instance's formatting, tooltips, theming and drill-through. Styling is never a reason to draw it yourself.
+- **No**, or the user asked for a custom one — scorecards, timelines, calendar grids, one visual from several queries: draw it from `useMetabaseQuery` rows, with SVG or a chart library the app already has.
+- A KPI is `scalar`, `smartscalar`, `gauge` or `progress`; put what Metabase doesn't draw (a caption, stars) beside it.
+- `InteractiveQuestion`: pass `isSaveEnabled={false}`, and `title={false}` in a panel with its own heading. Children replace its layout: `<InteractiveQuestion card={card}><InteractiveQuestion.QuestionVisualization height={360} /></InteractiveQuestion>` is the chart alone.
+
+**Visualization settings.** Add `visualizationSettings` only for a change the user asked for. Their keys are a question's `visualization_settings` keys — the `visualization` skill lists them — and the installed types decide what's legal: `rg -n "<key>|declare type .*VisualizationSettings" node_modules/@metabase/embedding-sdk-react/dist/index.d.ts`, never the whole file, never from memory. Keep them few: keys such as `graph.dimensions`, `pie.metric` and `column_settings` name result columns and break when the question changes.
+
+- A `table` with two breakouts and one aggregation renders as a pivot when a breakout has at most 16 values; `{ "table.pivot": false }` keeps one row per group.
+- A scalar shows the first column: with a key column first, point it at the number with `{ "scalar.field": "avg_rating" }`.
+- A header: `column_settings: { '["name","approvers"]': { column_title: "Approvers" } }`.
+
+## Pages
+
+No router library — it calls `history.pushState`, which the sandbox blocks. Wrap the app once in `<DataAppRouter>`, link with `<DataAppLink to="/customers/42">` (an `<a href>` that takes the usual anchor props), and read `{ pathname, navigate }` from `useDataAppLocation()`. There's no `useParams`: match `pathname` yourself.
+
+```tsx
+const TABS = [
+  { path: "/", label: "Overview", render: () => <Overview /> },
+  { path: "/customers", label: "Customers", render: () => <Customers /> },
+];
+// `/` and any unknown path open the first tab
+const activeTab = (pathname: string) =>
+  TABS.find((tab) => tab.path !== "/" && pathname.startsWith(tab.path)) ?? TABS[0];
+
+function Page() {
+  const { pathname } = useDataAppLocation();
+  const customerId = pathname.match(/^\/customers\/(\d+)$/)?.[1];
+  return customerId ? <CustomerDetail id={Number(customerId)} /> : activeTab(pathname).render();
+}
+// nav: <DataAppLink to={tab.path} aria-current={tab === activeTab(pathname) ? "page" : undefined}>
+// App: <DataAppRouter><Nav /><Page /></DataAppRouter>
+```
+
+Metabase mirrors each route to `/apps/<slug>/<path>`, and a reload there opens that page. A middle-click opens a new tab only in the preview; in Metabase that tab shows "This data app can't be opened directly." Check in the preview: reload on a sub-path, then on `/` — the first tab shows, marked selected.
+
+## Before handoff
+
+`npm run dev` only transpiles: run `npm run typecheck` after every round of edits and fix what it reports, and report the result, errors grouped by cause. Search the changed files and fix what turns up: `card={{` (every `card` comes from `useMemo`), `row[0]` and `as unknown as` (rows are keyed by column name), `<select` for a list from a question (`data-app-filters`), `type="date"` and `new Date(` in a date filter, `* 100` and `%`. Read the diagnostics feed with every panel mounted, then build and publish (`data-app`, _Build and publish_).

package/skill-data/git-sync/SKILL.md

@@ -24,7 +24,7 @@ Exporting after the remote moved on ends in a `conflict` task unless the export
 <!-- /requires -->
 
 ```bash
-mb git-sync status              --profile <n> --json   # → branch, dirty, current task
+mb git-sync status              --profile <n> --json   # → remote configured, sync type, branch, dirty, current task
 mb git-sync is-dirty            --profile <n> --json   # → {is_dirty: bool}; instance has unexported changes
 mb git-sync dirty               --profile <n> --json   # → list the dirty objects
 mb git-sync current-task        --profile <n> --json   # → in-flight task (or idle)
@@ -197,7 +197,7 @@ Both verbs return `{ success: true }`, plus a `task_id` only when the toggle sta
 
 **Cascade.** A toggle on a parent cascades to every descendant by `location` prefix — `add-collection 4` flips `4` plus every collection nested under it. `remove-collection 4` is the symmetric inverse. There is no per-leaf-only mode.
 
-**Mode prerequisite.** The server rejects toggles while `remote-sync-type` is `:read-only` (the install default). If `mb git-sync add-collection 12` returns `Metabase returned 400 … Cannot change synced collections when remote-sync-type is read-only.`, switch first with:
+**Mode prerequisite.** The server rejects toggles while `remote-sync-type` is `:read-only` (the install default; `mb git-sync status --json` reports it as `sync_type`). If `mb git-sync add-collection 12` returns `Metabase returned 400 … Cannot change synced collections when remote-sync-type is read-only.`, switch first with:
 
 ```bash
 mb setting set remote-sync-type '"read-write"' --profile <n>
@@ -256,7 +256,7 @@ Flagging the collection records it for the next export, which serializes its cur
 - Don't turn instance-side changes into hand-written repo files: export them and PR the exported branch (see the top of this skill). Files pushed behind Metabase's back race its own sync tasks.
 - Don't conclude from an empty `dirty` list that a change type isn't tracked. Dirty-tracking only records changes to _eligible_ objects; the usual cause is scope (the collection isn't flagged — see "Published table metadata"), not capability. Check `synced_collections` in `status` before concluding.
 - Don't run `git-sync import --force` or `git-sync export --force` without explicit user confirmation. Both are lossy — `--force` import discards instance-side work, `--force` export overwrites the remote branch.
-- Don't drive `git-sync` against a Metabase instance that doesn't have remote-sync configured — every verb returns an error pointing at the missing `remote-sync-*` settings. To check: `mb setting get remote-sync-url --profile <n> --json`.
+- Don't drive `git-sync` against a Metabase instance that doesn't have remote-sync configured — every verb returns an error pointing at the missing `remote-sync-*` settings. To check: `mb git-sync status --profile <n> --json` reports `remote_configured: false` when no remote is configured.
 - Don't author content directly via `card create` / `transform create` and then assume `git-sync export` will commit it cleanly — the instance and repo can drift if you mix direct API writes with sync-tracked changes. If you do, follow direct writes immediately with `git-sync export -m "..."` to keep them in step.
 - Don't move a dashboard or question into a synced collection before what it depends on, and don't retry a `Uses content that is not remote synced.` refusal unchanged. Move the listed dependencies first, move the whole containing collection, or build the content in the synced collection to begin with (see "Moving content into or out of a synced collection").
 - Don't omit `-m` on `export` if the user wants a meaningful commit message — the default server-generated message is generic.

package/skill-data/transform/SKILL.md

@@ -51,7 +51,7 @@ mb transform run "$TRANSFORM_ID" --wait --profile <name> --json
 - The `--json` envelope is shape-stable: `{message, run_id, final}` (plus `target_table_id` under `--sync` — a number, or `null` if the table didn't register before the timeout). `final` is `null` when `--wait` is omitted or the run never started, otherwise a full `TransformRun` with `status` and `message`. On a failed run (`final.status` ∈ {`failed`, `timeout`, `canceled`}) the CLI exits 1 and writes a one-line `transform run <id> failed` to stderr; the failure detail lives only in `final.message` on stdout, so `jq -r '.final.message'` is where to look.
 - `transform create --json` returns the agent-facing compact projection: `{id, name, description, source_type, target: {type, database, schema, name}, target_db_id}`. Read `target.schema`/`target.name` directly off it — no follow-up `transform get`.
 - If a transform with the same `name` already has a YAML representation on disk under the configured remote-sync repo, `create` mints a `_2` suffix on the exported filename (the new transform gets a fresh `entity_id`; the prior one isn't touched). For "iterate on the same concept", prefer `transform update <id>` — see "Iterating on a failing transform".
-- **`collection_id` only accepts a collection in the `:transforms` namespace.** Transforms aren't filed next to cards and dashboards — a normal analytics collection id fails create/update with `collection_id: A Transform can only go in Collections in the :transforms namespace.` Omit `collection_id` to leave the transform uncollected (the common case), or provision one with `mb collection create --body '{"name":"…"}' --namespace transforms --json` (see `core`) and pass the returned `id`. Cards and dashboards you build **on top of** the output table go in ordinary collections — so "put the transform and its dashboard in collection X" means _X holds the dashboard + cards; the transform stays in the transforms namespace._
+- **`collection_id` only accepts a collection in the `:transforms` namespace.** Transforms aren't filed next to cards and dashboards — a normal analytics collection id fails create/update with `collection_id: A Transform can only go in Collections in the :transforms namespace.` Omit `collection_id` to leave the transform uncollected (the common case), or reuse one from `mb collection list --namespace transforms --json`, or provision one with `mb collection create --body '{"name":"…"}' --namespace transforms --json` (see `core`) and pass the returned `id`. Cards and dashboards you build **on top of** the output table go in ordinary collections — so "put the transform and its dashboard in collection X" means _X holds the dashboard + cards; the transform stays in the transforms namespace._
 
 ## Inspect
 

package/dist/db-m5bQcXdn.mjs

@@ -1,24 +0,0 @@
-import { t as defineCommandGroup } from "./group-81zoQcEP.mjs";
-//#region src/commands/db/index.ts
-var db_default = defineCommandGroup({
-	name: "db",
-	description: "Inspect and sync Metabase databases",
-	alias: "database",
-	skills: [{
-		skill: "core",
-		purpose: "the database traversal ladder and schema sync"
-	}, {
-		skill: "data-workflow",
-		purpose: "model a raw database into clean tables"
-	}],
-	subCommands: {
-		list: () => import("./list-B5kRBn7k.mjs").then((m) => m.default),
-		get: () => import("./get-CWyRAHpz.mjs").then((m) => m.default),
-		schemas: () => import("./schemas-CHMD0HrY.mjs").then((m) => m.default),
-		"schema-tables": () => import("./schema-tables-CeW0kpA5.mjs").then((m) => m.default),
-		"sync-schema": () => import("./sync-schema-CewUOkmm.mjs").then((m) => m.default),
-		"rescan-values": () => import("./rescan-values-DAp_avxY.mjs").then((m) => m.default)
-	}
-});
-//#endregion
-export { db_default as default };

package/dist/delete-runtime-CkNvZfFA.mjs

@@ -1,55 +0,0 @@
-import { _ as promptConfirm, c as renderSummary, yt as ConfigError } from "./cli.mjs";
-import { z } from "zod";
-//#region src/commands/delete-runtime.ts
-const DeleteResult = z.object({
-	deleted: z.boolean(),
-	aborted: z.boolean(),
-	id: z.number().int()
-});
-const deleteResultView = {
-	compactPick: DeleteResult,
-	tableColumns: [
-		{
-			key: "id",
-			label: "ID"
-		},
-		{
-			key: "deleted",
-			label: "Deleted"
-		},
-		{
-			key: "aborted",
-			label: "Aborted"
-		}
-	]
-};
-async function confirmDestructive(args) {
-	if (args.yes) return true;
-	if (process.stdin.isTTY !== true) throw new ConfigError(`refusing to ${args.action} without confirmation — pass --yes to proceed non-interactively`);
-	return promptConfirm({
-		message: args.promptMessage,
-		initialValue: false
-	});
-}
-async function confirmAndDelete(args) {
-	if (!await confirmDestructive({
-		yes: args.yes,
-		action: `delete ${args.id}`,
-		promptMessage: args.promptMessage
-	})) {
-		renderSummary({
-			deleted: false,
-			aborted: true,
-			id: args.id
-		}, deleteResultView, args.abortMessage, args.ctx);
-		return;
-	}
-	await args.deleteResource();
-	renderSummary({
-		deleted: true,
-		aborted: false,
-		id: args.id
-	}, deleteResultView, args.successMessage, args.ctx);
-}
-//#endregion
-export { confirmAndDelete as n, confirmDestructive as r, DeleteResult as t };

package/dist/embedding-i-KqpefC.mjs

@@ -1,9 +0,0 @@
-import { z } from "zod";
-//#region ../client/src/domain/embedding.ts
-const EmbeddingParams = z.record(z.string(), z.enum([
-	"disabled",
-	"enabled",
-	"locked"
-]));
-//#endregion
-export { EmbeddingParams as t };

package/dist/git-sync-BwkWeJAz.mjs

@@ -1,29 +0,0 @@
-import { t as defineCommandGroup } from "./group-81zoQcEP.mjs";
-//#region src/commands/git-sync/index.ts
-var git_sync_default = defineCommandGroup({
-	name: "git-sync",
-	description: "Sync Metabase content with a git remote",
-	skills: [{
-		skill: "git-sync",
-		purpose: "import/export round-trip and dirty checks"
-	}],
-	subCommands: {
-		status: () => import("./status-BtWz7Pzn.mjs").then((mod) => mod.default),
-		"is-dirty": () => import("./is-dirty-TDcfeOde.mjs").then((mod) => mod.default),
-		"has-remote-changes": () => import("./has-remote-changes-BsS3XB0P.mjs").then((mod) => mod.default),
-		dirty: () => import("./dirty-fYlA1N1e.mjs").then((mod) => mod.default),
-		"current-task": () => import("./current-task-nl2z8sHI.mjs").then((mod) => mod.default),
-		"cancel-task": () => import("./cancel-task-BiTlDY7a.mjs").then((mod) => mod.default),
-		wait: () => import("./wait-BV6JOdgi.mjs").then((mod) => mod.default),
-		import: () => import("./import-CXd5HdB0.mjs").then((mod) => mod.default),
-		export: () => import("./export-YtdZo7LZ.mjs").then((mod) => mod.default),
-		"export-preflight": () => import("./export-preflight-Db_TChn5.mjs").then((mod) => mod.default),
-		stash: () => import("./stash-Dj-mnIa4.mjs").then((mod) => mod.default),
-		branches: () => import("./branches-lPHtM_xR.mjs").then((mod) => mod.default),
-		"create-branch": () => import("./create-branch-CUNFdKyB.mjs").then((mod) => mod.default),
-		"add-collection": () => import("./add-collection-BnGPc0Vv.mjs").then((mod) => mod.default),
-		"remove-collection": () => import("./remove-collection-cxSSFxza.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { git_sync_default as default };

package/dist/input-AXP2LCOV.mjs

@@ -1,61 +0,0 @@
-import { jt as isFileNotFoundError, yt as ConfigError } from "./cli.mjs";
-import { readFile } from "node:fs/promises";
-import { setTimeout } from "node:timers/promises";
-//#region src/runtime/input.ts
-const DEFAULT_FLAG_NAME = "--body";
-const SOURCE_LIST = `${DEFAULT_FLAG_NAME}, --file, stdin, or a positional argument`;
-/** The value of a string flag, or `null` when it was left out or passed empty. */
-function givenValue(value) {
-	return value === void 0 || value === "" ? null : value;
-}
-async function readInput(sources) {
-	if (sources.flag) return sources.flag;
-	if (sources.file) return await readFileSource(sources.file);
-	if (!process.stdin.isTTY) {
-		const piped = await readPipedStdin();
-		if (piped) return piped;
-	}
-	if (sources.positional) return sources.positional;
-	if (sources.required ?? true) throw new ConfigError(`input required: provide one of ${SOURCE_LIST}`);
-	return "";
-}
-async function readFileSource(path) {
-	if (path === "-") return await drainStdin();
-	try {
-		return await readFile(path, "utf8");
-	} catch (error) {
-		if (isFileNotFoundError(error)) throw fileNotFoundError(path);
-		throw error;
-	}
-}
-function fileNotFoundError(path) {
-	return new ConfigError(`--file not found: ${path}`);
-}
-async function drainStdin() {
-	let data = "";
-	for await (const chunk of process.stdin) data += chunk;
-	return data;
-}
-const STDIN_FIRST_CHUNK_TIMEOUT_MS = 500;
-const STDIN_IDLE = Symbol("stdin-idle");
-async function readPipedStdin() {
-	const iterator = process.stdin[Symbol.asyncIterator]();
-	const controller = new AbortController();
-	const idle = setTimeout(STDIN_FIRST_CHUNK_TIMEOUT_MS, STDIN_IDLE, { signal: controller.signal }).catch(() => STDIN_IDLE);
-	const first = await Promise.race([iterator.next(), idle]);
-	if (typeof first === "symbol") {
-		process.stdin.pause();
-		process.stdin.unref();
-		return null;
-	}
-	controller.abort();
-	let data = "";
-	let chunk = first;
-	while (chunk.done !== true) {
-		data += chunk.value;
-		chunk = await iterator.next();
-	}
-	return data;
-}
-//#endregion
-export { readInput as i, fileNotFoundError as n, givenValue as r, DEFAULT_FLAG_NAME as t };