@metabase/cli 0.5.2 → 0.5.4

package/skill-data/data-app/template/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "strict": true,
+    "allowJs": false,
+    "checkJs": false,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/skill-data/data-app/template/vite.config.ts

@@ -0,0 +1,3 @@
+import { dataAppConfig } from "@metabase/embedding-sdk-react/data-app-dev/config";
+
+export default dataAppConfig();

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

@@ -0,0 +1,96 @@
+---
+name: data-app-actions
+description: Make a Metabase data app write data — an action in the app's collection, its typed definition in `src/metabase.ts`, and the `useAction` hook from `@metabase/embedding-sdk-react/data-app` behind a form or a button, with inputs typed from each parameter, the server's error shown as it comes, and every affected query refreshed. Triggers — "a form that saves a row", "a button that updates a record", "delete an entry from the app", "submit doesn't refresh the list", "the action fails in the app". Creating the action itself is `data-action`; reads are `data-app-data`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+requires: [dataApps]
+---
+
+# Writes in a data app
+
+An **action** is a saved, parameterized SQL write — `INSERT`, `UPDATE` or `DELETE`. A data app runs only the actions in **the app's collection** (`data-app`, _Create the app_).
+
+1. Draft the action as `data-action` describes — the database must allow actions — with `collection_id` the app's collection. Show the user its SQL and parameters, and create it once they agree.
+2. Regenerate `src/metabase.ts` (`data-app-data`).
+3. Pass `actions.<name>` from it to `useAction`.
+
+Each action there lists its parameters: the parameter slug (the key `execute` takes), `displayName` (a label, never a key), `jsType` (`string`, `number`, `Date`, `boolean` or `unknown`) and `required`. Never fake a call to an action `src/metabase.ts` doesn't list.
+
+## The hook
+
+```tsx
+import { useAction } from "@metabase/embedding-sdk-react/data-app";
+import { actions } from "../metabase";
+
+const { execute, isExecuting, result, error, reset } = useAction(actions.setOrderNote);
+```
+
+- **Import it from `/data-app`.** The main `@metabase/embedding-sdk-react` entry exports the general SDK `useAction`, which takes raw ids and isn't typed from the definition. Write no generics: the definition types `execute`'s keys and values.
+- `execute(params)` resolves to the response body; on failure it both throws and sets `error`. It resolves to `null` without sending anything while the SDK is still starting, so guard a call that can happen at mount. It never runs on its own and has no `enabled`: return early in the handler to skip it.
+- `isExecuting` is true until it settles: disable the trigger and show progress, so a double click can't send twice.
+- `result` is the last response, `null` before the first call; `result?.["rows-affected"]` is a quick confirmation. `reset()` clears `result` and `error`, for example when the user dismisses a message.
+
+## A form
+
+```tsx
+export function NoteForm({ orderId, onSaved }: { orderId: number; onSaved: () => Promise<void> }) {
+  const { execute, isExecuting, error } = useAction(actions.setOrderNote);
+  const [note, setNote] = useState("");
+  const [isValid, setIsValid] = useState(false);
+
+  async function onSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    try {
+      await execute({ order_id: orderId, note }); // keys are parameter slugs
+      await onSaved(); // the parent refetches what the write changed
+      setNote("");
+    } catch {
+      // shown from `error`
+    }
+  }
+
+  return (
+    <form onSubmit={onSubmit} onChange={(event) => setIsValid(event.currentTarget.checkValidity())}>
+      <input type="text" required value={note} onChange={(event) => setNote(event.target.value)} />
+      <button type="submit" disabled={isExecuting || !isValid}>
+        {isExecuting ? "Saving…" : "Save"}
+      </button>
+      {error ? (
+        <pre style={{ whiteSpace: "pre-wrap", margin: 0 }}>
+          {error.data.message ?? "Action failed."}
+        </pre>
+      ) : null}
+    </form>
+  );
+}
+```
+
+**Inputs.** Pick each input's type from `jsType`, never from the parameter slug — one called `email` with `jsType: "string"` is still `type="text"`.
+
+| `jsType`  | Input                                                      |
+| --------- | ---------------------------------------------------------- |
+| `string`  | `type="text"`                                              |
+| `number`  | `type="number"`, read with `valueAsNumber`                 |
+| `boolean` | a checkbox or switch                                       |
+| `Date`    | `type="date"`, or `datetime-local` when a time is expected |
+| `unknown` | `type="text"`, converted at the call                       |
+
+**Validation** is `required` on each required parameter and nothing else — no length, range or format checks of your own. Disable submit from the browser's verdict, `form.checkValidity()`, never from hand-rolled checks. Anything stricter comes back from the server.
+
+**Errors.** `error` is `{ status?, data: { message?, errors? }, isCancelled }` — read it without a cast. A failing SQL action comes back as a 500 whose `data.message` wraps the driver's text (`Error executing Action: …`): show it as it comes, in a `white-space: pre-wrap` element, since driver messages span lines — never "Something went wrong", `String(error)` or a friendlier paraphrase. `error.data.errors?.[parameterSlug]`, when present, goes beside its field (`aria-invalid` on the input).
+
+## Refresh
+
+After a write succeeds, refetch every query on screen it could have changed: `await Promise.all([orders.refetch(), totals.refetch()])`, the `refetch` that `useMetabaseQuery` returns.
+
+- Those queries live in a component above the trigger, which passes the refresh down; a query in the trigger's own component or below it can't be wired to it.
+- Await the refresh before clearing the form or closing the modal, so stale rows never flash.
+- Never prepend `result` to a local list instead: ids, timestamps and computed columns come from the server.
+
+## When it doesn't work
+
+1. Log `result`, `error` and the object passed to `execute`: every key is a parameter slug, every value matches its `jsType`.
+2. `execute` resolved to `null` and nothing was sent: it ran before the SDK started.
+3. The screen doesn't update: see _Refresh_.
+4. The action is missing from `src/metabase.ts`: it isn't in the app's collection, or the file is stale — regenerate it.
+
+Then build and publish (`data-app`, _Build and publish_).

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/mbql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mbql
-description: Author and debug MBQL query bodies for the `mb` CLI — the query shape, clauses, filters, aggregation and breakout, order and limit, expressions, joins and FK columns, multi-stage pipelines, saved questions and definitions as sources, output column names, and the print-schema → dry-run → run loop. Use when writing or fixing any query body — `mb query`, a card's `dataset_query`, a transform's `source.query`, or a segment/measure `definition` — or when `--dry-run` or a run reports errors. Triggers — "write an MBQL query", "the dataset_query is wrong", "aggregate and group by", "join two tables", "month-over-month".
+description: Author and debug MBQL query bodies for the `mb` CLI — the query shape, clauses, filters, aggregation and breakout, order and limit, expressions, joins and FK columns, multi-stage pipelines, saved questions and definitions as sources, output column names, and the schema → dry-run → run loop. Use when writing or fixing any query body — `mb query`, a card's `dataset_query`, a transform's `source.query`, or a segment/measure `definition` — or when `--dry-run` or a run reports errors. Triggers — "write an MBQL query", "the dataset_query is wrong", "aggregate and group by", "join two tables", "month-over-month".
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -147,12 +147,12 @@ A measure is an aggregation, `["measure", {}, <measure id>]`, on its table, and
 
 <!-- /requires -->
 
-## Authoring loop: print-schema → dry-run → run
+## Authoring loop: schema → dry-run → run
 
 ```bash
 mb query --file q.json --dry-run --profile <n>        # check + compile on the server, no run
 mb query --file q.json --profile <n> --json           # check + run
-mb query --print-schema --profile <n> > ./.scratch/mbql-schema.json   # the full JSON Schema
+mb schema query > ./.scratch/mbql-schema.json         # the JSON Schema bundle, no server needed
 mb query --file q.json --compile --profile <n>        # the SQL the server generates
 mb query --file q.json --metadata --profile <n> --json   # tables (with FK targets), fields, snippets it touches
 mb query --file q.json --export-format csv --profile <n> > rows.csv   # stream the rows up to the server's download limit, no envelope cap

package/skill-data/native-sql/SKILL.md

@@ -28,7 +28,7 @@ A native `dataset_query` is a query with one **native stage** — the `lib/type:
 }
 ```
 
-This is the form a card stores and returns — author it. The CLI **pre-flight-validates** it — the envelope, the template-tag shapes, the field refs — through the usual `--print-schema → --dry-run → run` loop (`mbql`), and a saved card **round-trips** in exactly this shape: `mb card get <id> --full --json`, edit the `stages[0].native` string, send it straight back. Only the warehouse parses the SQL string, so a **SQL** syntax error surfaces when you run it, not at `--dry-run`. A parameterless query needs no `template-tags` — just the `native` string.
+Author it in this form. The CLI **pre-flight-validates** it — the envelope, the template-tag shapes, the field refs — through the usual `mb schema query` → `--dry-run` → run loop (`mbql`). A saved card **round-trips**: `mb card get <id> --full --json` returns the same stage with `template-tags` as a list of the same entries, each carrying its `name`; edit the `stages[0].native` string and send it straight back, list and all. Only the warehouse parses the SQL string, so a **SQL** syntax error surfaces when you run it, not at `--dry-run`. A parameterless query needs no `template-tags` — just the `native` string.
 
 You may see an older flat form in cards created long ago — `{database, type:"native", native:{query}}`. The server still accepts it (it normalizes to the above) but it skips pre-flight and doesn't round-trip — **don't author it**.
 

package/skill-data/native-sql/references/template-tags.md

@@ -4,7 +4,7 @@ Every template-tag body, the widget-type vocabulary, and the parameter-object sh
 
 ## Template-tag bodies by `type`
 
-The `template-tags` value is a map keyed by tag name; each entry's `name` must equal its key and the `{{name}}` in the SQL. `id` is any string unique among the tags; the tag's name serves.
+Author the `template-tags` value as a map keyed by tag name; each entry's `name` must equal its key and the `{{name}}` in the SQL. A card read back carries the same entries as a list, which the server also takes. `id` is any string unique among the tags; the tag's name serves.
 
 ### Raw variable — `text` / `number` / `date` / `boolean`
 

package/dist/body-C0VnEiRV.mjs

@@ -1,16 +0,0 @@
-import { St as ConfigError, Z as parseJson } from "./cli.mjs";
-import { E as DEFAULT_FLAG_NAME, O as givenValue, k as readInput } from "./runtime-Cmes70jO.mjs";
-//#region src/runtime/body.ts
-async function readBody(sources, schema) {
-	assertSingleSource(sources);
-	return parseJson(await readInput(sources), schema, { source: sources.source ?? "request body" });
-}
-function assertSingleSource(sources) {
-	const provided = [];
-	if (givenValue(sources.flag) !== null) provided.push(DEFAULT_FLAG_NAME);
-	if (givenValue(sources.file) !== null) provided.push("--file");
-	if (givenValue(sources.positional) !== null) provided.push("positional");
-	if (provided.length > 1) throw new ConfigError(`multiple body sources given (${provided.join(", ")}); pass exactly one`);
-}
-//#endregion
-export { readBody as t };

package/dist/card-BnL92zoT.mjs

@@ -1,25 +0,0 @@
-import { t as defineCommandGroup } from "./group-81zoQcEP.mjs";
-//#region src/commands/card/index.ts
-var card_default = defineCommandGroup({
-	name: "card",
-	description: "Manage Metabase cards (questions, models, metrics)",
-	skills: [{
-		skill: "mbql",
-		purpose: "author the dataset_query"
-	}, {
-		skill: "visualization",
-		purpose: "choose display and visualization_settings"
-	}],
-	subCommands: {
-		list: () => import("./list-C6roDyBd.mjs").then((mod) => mod.default),
-		get: () => import("./get-Be7yjY9v.mjs").then((mod) => mod.default),
-		query: () => import("./query-CzDBwAZD.mjs").then((mod) => mod.default),
-		alerts: () => import("./alerts-CyB1Z7AU.mjs").then((mod) => mod.default),
-		create: () => import("./create-B3QZpifA.mjs").then((mod) => mod.default),
-		update: () => import("./update-BtfUX9CN.mjs").then((mod) => mod.default),
-		verify: () => import("./verify-C-StvB4f.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-CfNLlebd.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { card_default as default };

package/dist/collection-DRHGwFSL.mjs

@@ -1,21 +0,0 @@
-import { t as defineCommandGroup } from "./group-81zoQcEP.mjs";
-//#region src/commands/collection/index.ts
-var collection_default = defineCommandGroup({
-	name: "collection",
-	description: "Manage Metabase collections",
-	skills: [{
-		skill: "core",
-		purpose: "collection ref forms and the transforms namespace"
-	}],
-	subCommands: {
-		list: () => import("./list-CpxEOoqw.mjs").then((mod) => mod.default),
-		get: () => import("./get-RCDF-hEq.mjs").then((mod) => mod.default),
-		items: () => import("./items-mIoZBqUc.mjs").then((mod) => mod.default),
-		tree: () => import("./tree-Ddsj298M.mjs").then((mod) => mod.default),
-		create: () => import("./create-Dn8V5siS.mjs").then((mod) => mod.default),
-		update: () => import("./update-_hHnM1Hx.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-DpgtAdEa.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { collection_default as default };