@metabase/cli 0.5.8 → 0.5.10

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

@@ -1,50 +1,72 @@
 ---
 name: data-app-actions
-description: Make a Metabase data app write data — an action in the app's collection (a table action that inserts, updates or deletes a row, or a SQL query action), 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`.
+description: Make a Metabase data app write data — a table action that inserts, updates or deletes a row of a published table, defined with `defineAction` in `src/metabase.actions.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". Reads are `data-app-data`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 requires: [dataApps]
 ---
 
 # Writes in a data app
 
-An **action** is a table action, which inserts, updates or deletes one row of a table, or a query action, a saved SQL write (`data-action`). A data app runs only the actions in **the app's collection** (`data-app`, _Create the app_).
+A data app writes through **table actions**: an insert, update or delete of one row of a table published to the Library, by its primary key. It defines each one in `src/metabase.actions.ts`, one export per action:
 
-1. Draft the action as `data-action` describes, with `collection_id` the app's collection: the database must allow actions, and a table action's table must be published to the Library, as every table the app reads is. Pick the type as `data-action`, _Pick the type_, says. Show the user the table and kind, or the SQL, and the parameters; create it once they agree.
-2. Regenerate `src/metabase.ts` (`data-app-data`).
-3. Pass `actions.<name>` from it to `useAction`.
+```ts
+import { defineAction } from "@metabase/embedding-sdk-react/data-app";
 
-An action in the app's collection can't be archived: to drop one, move it to a data actions collection (`mb data-action update <id> --body '{"collection_id":<id>}'`), then archive it.
+import { schema } from "./metabase.schema";
 
-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.
+export const updateOrder = defineAction({
+  entityId: "J2mXq8sLb0vT5nYcW4kRd",
+  kind: "row/update",
+  table: schema.tables.orders,
+});
+```
+
+- `kind` is `row/create`, `row/update` or `row/delete`; `table` is a table of `schema` (`data-app-data`). The table needs exactly one primary key, and its database needs data actions turned on (_Data actions on the database_): settle both before writing the export. Show the user the table and kind and add it once they agree; a request that already names the write ("let me add a note") is that agreement.
+- `entityId` comes from `mb nano-id`, never invented; keep it when editing the export. The export's name is the action's name in Metabase.
+- There are no query actions and no SQL: a write a table action can't do (a computed value, several rows, a row matched by another column) is out of reach for the app — say so. Never copy an action from a data actions collection.
+- To drop an action, delete its export.
+
+The dev preview runs the action without saving it; Metabase runs it once the app is released (`data-app`, _Release_).
+
+## Data actions on the database
+
+Before the first action on a database, read its toggle: `mb db get <db-id> --full --json --profile <name> | jq '.settings["database-enable-actions"]'` (`<db-id>` from `mb db list --profile <name> --json`, or `mb table get <table-id> --json --profile <name> | jq .db_id` once `src/metabase.schema.ts` gives the table's `id`). Anything but `true`, an unset `null` included, means it's off, and every action on that database fails with `Actions are not enabled.`, in the preview and in Metabase. Then ask with `AskUserQuestion` ("Data actions are off on <database>. Turning them on lets anyone with access to its actions write to it."), offering:
+
+- **Turn them on now**: run `mb db set-data-actions <db-id> true --profile <name>`, then read the toggle again.
+- **I'll turn them on**: the user does it in Admin → Databases → the database ("Allow data actions that use this database to be run"); wait for them, then read the toggle again before going on.
+- **No writes**: build the app without actions, and tell the user which features that leaves out.
+
+Never turn the toggle on without that yes.
 
 ## The hook
 
 ```tsx
 import { useAction } from "@metabase/embedding-sdk-react/data-app";
-import { actions } from "../metabase";
+import { updateOrder } from "../metabase.actions";
 
-const { execute, isExecuting, result, error, reset } = useAction(actions.setOrderNote);
+const { execute, isExecuting, result, error, reset } = useAction(updateOrder);
 ```
 
 - **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; a query action answers `{"rows-affected": <n>}`, a table action `rows-updated`, `rows-deleted` or `created-row` (`data-action`, _Table actions_). `reset()` clears `result` and `error`, for example when the user dismisses a message.
+- `result` is the last response, `null` before the first call: `{ "created-row": <the new row> }` for an insert, `{ "rows-updated": <n> }` for an update, `{ "rows-deleted": <n> }` for a delete. `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 { execute, isExecuting, error } = useAction(updateOrder);
   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 execute({ id: orderId, note }); // keys are column names, in lowercase
       await onSaved(); // the parent refetches what the write changed
       setNote("");
+      setIsValid(false);
     } catch {
       // shown from `error`
     }
@@ -66,25 +88,23 @@ export function NoteForm({ orderId, onSaved }: { orderId: number; onSaved: () =>
 }
 ```
 
-**Inputs.** Pick each input's type from `jsType`, never from the parameter slug — one called `email` with `jsType: "string"` is still `type="text"`.
+**Parameters.** The keys `execute` takes are the table's column names in lowercase (`CREATED_AT` becomes `created_at`; names already in lowercase stay as they are), each typed from its field's `jsType` in `src/metabase.schema.ts`, and all optional in the type. Pick each input from `jsType`, never from the name — a column called `email` with `jsType: "string"` is still `type="text"`.
 
 | `jsType`  | Input                                                      |
 | --------- | ---------------------------------------------------------- |
-| `string`  | `type="text"`                                              |
+| `string`  | `type="text"`; a `<textarea>` for long text such as a note |
 | `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                       |
 
-**Table actions.** The parameter slugs are the table's column names, slugified.
-
-- **Insert** (`row/create`): every column but an auto-increment key. `result["created-row"]` holds the new row's parameter columns, its key among them.
-- **Update** (`row/update`): the key and every other column, `required` on each `NOT NULL` one without a default. Start the form from the row's current values, read by the query on screen, and send them all. A `null` is dropped, so an update can't clear a column.
+- **Insert** (`row/create`): every column but an auto-increment key and the columns the database fills when the form leaves them out, such as a `created_at` or `status` with a default. `mb table get <id> --include fields --full --json` gives each field's `database_required` and `database_default`. `result["created-row"]` holds the new row, its key among them.
+- **Update** (`row/update`): the key and the columns to change. An edit form starts from the row's current values, read by the query on screen, and sends them all; a button that sets one column (mark as done) sends only the key and that column. A fixed value such as `"done"` comes from the column's values (`mb field values <field-id> --profile <name>`), never a guess. A `null` is dropped, so an update can't clear a column.
 - **Delete** (`row/delete`): the key only. Ask the viewer to confirm first.
 
-**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.
+**Validation** is `required` on the key of an update or delete and on each `NOT NULL` column without a default in an insert, 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 query 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. A table action's refusals and constraint errors are 400s, shown the same way (`Sorry, the row you're trying to update doesn't exist`). `error.data.errors?.[parameterSlug]`, when present, goes beside its field (`aria-invalid` on the input).
+**Errors.** `error` is `{ status?, data: { message?, errors? }, isCancelled }` — read it without a cast. Refusals and constraint errors are 400s whose `data.message` carries the server's text (`Sorry, the row you're trying to update doesn't exist`): 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?.[parameter]`, when present, goes beside its field (`aria-invalid` on the input).
 
 ## Refresh
 
@@ -97,9 +117,9 @@ After a write succeeds, refetch every query on screen it could have changed: `aw
 
 ## 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`.
+1. Log `result`, `error` and the object passed to `execute`: every key is a lowercase column name, 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.
+4. It works in the preview but not in Metabase: the app was released without running `mb data-app generate-actions` (`data-app`, _Release_).
 
-Then build and publish (`data-app`, _Build and publish_).
+Then release the app (`data-app`, _Release_).

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

@@ -1,6 +1,6 @@
 ---
 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`.
+description: Give a Metabase data app its data — `src/metabase.schema.ts` from `mb data-app generate-schema`, questions over the Library's published tables and metrics as `defineQuery` exports in `src/metabase.queries.ts`, their entity IDs from `mb nano-id`, 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 the schema". Creating and releasing 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]
 ---
@@ -9,40 +9,68 @@ requires: [dataApps]
 
 Before changing an existing app, pass the checks in `data-app`, _An existing project_: the template's config and factory, and React 19.
 
-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:
+A data app runs only the questions and actions it defines; its viewers can read nothing else. So every piece of data starts in its source:
 
-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.
+1. Fetch `src/metabase.schema.ts` (below).
+2. Define a question in `src/metabase.queries.ts` (below) or an action in `src/metabase.actions.ts` (`data-app-actions`).
+3. Pass the export to a hook. The dev preview runs it at once; Metabase runs it once the app is released (`data-app`, _Release_).
 
 ## Sources: the semantic layer only
 
-An app reads only what the user curated in the Library. Metabase refuses a question in the app's collection that breaks these rules:
+An app reads only what the user curated in the Library, and `src/metabase.schema.ts` holds exactly that. Metabase refuses a question that breaks these rules:
 
-- **Tables published to the Library**, and nothing else: `mb table list --published-only --json`. That covers the question's source table, every join, every table reached through a foreign key column, the tables behind its segments and measures, and the tables whose columns Metabase shows in place of a foreign key.
-- **Metrics in the Library's Metrics collection**, as aggregations (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.
-- **No other question as a source** — not a question in the app's collection, a model or a metric. Every question starts from a published table.
-- **MBQL only**, never native SQL.
+- **Tables published to the Library**, and nothing else: the source table, every table reached through a foreign key column, and the tables behind its segments and measures.
+- **Metrics in the Library**, as aggregations, and the segments and measures of published tables. Prefer one that matches the concept over rebuilding it with filters and thresholds of your own.
+- **No other question as a source** — not one of the app's own, a model or a metric. Every question starts from a published table.
+- **One stage of MBQL**, never native SQL, with no explicit joins and no custom columns: reach another table through a foreign key column, and compute in the app.
 
 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.
 
+## `src/metabase.schema.ts`
+
+```bash
+cd <repo> && mb data-app generate-schema <slug> --profile <name>
+```
+
+From the repository root, this writes `data_apps/<slug>/src/metabase.schema.ts`: the Library's published tables with their fields, segments and measures, and the Library's metrics, each keyed by its camelCased name, with its numeric ID. It exports `schema` (`import { schema } from "./metabase.schema"`). Fetch it again after the user publishes a table or changes its metadata, then `npm run typecheck`, which catches code still using a renamed or removed field. Never edit the file.
+
+The numeric IDs are that instance's, so the dev preview runs against it alone; a production build runs each question by its `entityId` instead, on every instance the app is imported to.
+
 ## 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:
+`src/metabase.queries.ts` holds one export per question:
 
-```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]}'
+```ts
+import {
+  aggregations,
+  breakout,
+  defineQuery,
+  orderBy,
+} from "@metabase/embedding-sdk-react/data-app";
+
+import { schema } from "./metabase.schema";
+
+const orders = schema.tables.orders;
+
+export const revenueByMonth = defineQuery({
+  entityId: "Vh3kq0wYc8TnS2aJm1LxR",
+  source: orders,
+  aggregations: [aggregations.sum(orders.fields.total, { name: "revenue" })],
+  breakouts: [breakout(orders.fields.createdAt, { unit: "month" })],
+});
+
+export const latestReviews = defineQuery({
+  entityId: "pW9dE4uNq7Zb1fGhK3sTy",
+  source: schema.tables.reviews,
+  orderBys: [orderBy(schema.tables.reviews.fields.createdAt, "desc")],
+  limit: 20,
+});
 ```
 
+- `source` is a table of `schema`; `aggregations`, `breakouts`, `filters`, `orderBys`, `limit` and `fields` (the columns to keep) take its fields, its segments and measures, and the metrics of `schema.metrics` as aggregations (`aggregations: [schema.metrics.revenue]`). A field that isn't the table's, or an operator its type doesn't take, fails to compile.
+- The export's name is the question's name in Metabase, as written (`customerList`).
+- Each `entityId` comes from `mb nano-id` (`mb nano-id --count <n>` for several), never invented or copied. Keep an export's `entityId` when you edit it: a new one replaces the question with another.
+
 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.
@@ -51,38 +79,11 @@ Plan the questions from what the app shows and picks from — each chart, KPI, t
 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.
+- To drop a question, delete its export.
 
-## `src/metabase.ts`
+A result column's `name` keys the rows and names the column in runtime clauses: a field's `name` in `src/metabase.schema.ts`, in the database's own case (`CREATED_AT` here, `created_at` on Postgres), or an aggregation's — `count`, `sum`, or the `name` you gave it. Never take one from SQL:
 
-```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 column reached through a foreign key keeps its own name (`CATEGORY`, not `PRODUCTS__via__PRODUCT_ID__CATEGORY`).
 - 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.
 
@@ -90,15 +91,36 @@ A column's `name` keys the rows and names the column in runtime clauses. Take it
 
 ```tsx
 import { useMetabaseQuery } from "@metabase/embedding-sdk-react/data-app";
-import { queries } from "../metabase";
+import { revenueByMonth } from "../metabase.queries";
 
-const { data, error, refetch } = useMetabaseQuery(queries.revenueByMonth);
-const rows = data?.rows ?? []; // row.CREATED_AT, row.sum, typed from jsType
+const { data, error, refetch } = useMetabaseQuery(revenueByMonth);
+const rows = data?.rows ?? []; // row.CREATED_AT, row.revenue, 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.
+- `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 `isLoading` is true while a run is in flight (it stays false while held back), and `data.rows.length === 0` is empty.
+- `error` is `unknown`. A refused or failed query sets it to the response, `{ status, data }`, whose `data` is the server's message or an object with a `message`; anything else is an `Error`. Read it with one helper, which narrows without a cast, and render its message in the panel as it comes:
+
+```ts
+export function errorMessage(error: unknown): string {
+  if (typeof error === "object" && error !== null && "data" in error) {
+    const { data } = error;
+    if (typeof data === "string") {
+      return data;
+    }
+    if (
+      typeof data === "object" &&
+      data !== null &&
+      "message" in data &&
+      typeof data.message === "string"
+    ) {
+      return data.message;
+    }
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+```
+
 - 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`
@@ -110,7 +132,7 @@ 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 { query, isLoading, error } = useMetabaseQueryObject(revenueByMonth);
 const card = useMemo(() => ({ query, visualization: "line" }) satisfies MetabaseCard, [query]);
 
 // PanelError and Spinner are the app's own components
@@ -119,7 +141,7 @@ 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`.
+- Always pass `visualization`: 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.
 
@@ -131,7 +153,7 @@ Both hooks take a second argument: one object with the clauses the UI changes, a
 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, {
+const { query } = useMetabaseQueryObject(orderRows, {
   filters:
     start && end ? [filter({ type: "column", name: "CREATED_AT" }, "between", [start, end])] : [],
   aggregations: [aggregations.sum({ type: "column", name: "TOTAL" }, { name: "revenue" })],
@@ -140,7 +162,7 @@ const { query } = useMetabaseQueryObject(queries.orderRows, {
 });
 ```
 
-- 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`).
+- A column is `{ type: "column", name }` with a result column's `name`, or a field of `schema`; 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                                                                                                             |
   | ----------- | --------------------------------------------------------------------------------------------------------------------- |
@@ -149,12 +171,12 @@ const { query } = useMetabaseQueryObject(queries.orderRows, {
   | 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.
+- `filter(...)` takes one value (`filter(col, "=", 42)`): `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.
+- `time-interval` (`[-30, "day"]`, `[0, "year"]` for this year) is relative to when the query runs: a fixed window belongs in the definition, 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. Never aggregate an aggregated question at runtime: a sum over its rows is wrong for distinct counts, averages, ratios and levels such as MRR. A runtime filter only picks its rows. So a date filter on it offers presets of whole, complete buckets at the question's own grain (Last month, Last 12 months on a month question), each range from the first bucket's start to the last bucket's start, and no Custom range; a KPI shows one bucket, as `scalar` (a `smartscalar` filtered to one bucket loses its comparison), with no All time. A filter on a column needs a question broken out by that column too; its All is no clause when the panel shows that column (a series per value), and otherwise a second question without that breakout, both hooks called and switched with `enabled`. When a request needs more, say so.
 - 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_).
+The controls that feed these clauses are `data-app-filters`. When the data is in place, release the app (`data-app`, _Release_).

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

@@ -26,7 +26,7 @@ Before any control, write one row per filter: the question that gives its option
 ## Values and options
 
 - Every filter starts at **All**, except a KPI's own date control (above). Keep it as `"all"` in state and send it as no clause (`[]`), except on an aggregated question whose panel doesn't show the filtered column, where All is its own question (`data-app-data`, _Runtime clauses_); 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.
+- Options come at runtime from their own question (`data-app-data`), 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:
 
@@ -40,7 +40,7 @@ useEffect(() => {
 
 ## 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:
+Any filter control 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. Picking a row in a list the page already shows (a customer table driving that customer's details) is not a filter control: the row click is the picker. 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.
@@ -92,4 +92,4 @@ const lastCompleteMonths = (n: number): [string, string] => {
 
 ## Check
 
-For every visible filter except a KPI's own date control: All runs the unfiltered question, or its All 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 unless it filters an aggregated question; 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_).
+For every visible filter except a KPI's own date control: All runs the unfiltered question, or its All 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 unless it filters an aggregated question; and no scope has two date controls. Search the filter controls for `<select` and `type="date"` — an action form keeps its date inputs. Then release the app (`data-app`, _Release_).

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

@@ -22,7 +22,7 @@ Everything here runs inside the sandbox, the same in the dev preview as in Metab
 ## 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.
+- Don't read a `rate`, `score`, `margin` or `percent` column as a percentage or threshold — no `%`, `* 100`, colors or stars — unless its field's `semanticType` in `src/metabase.schema.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.
 
@@ -38,7 +38,14 @@ Everything here runs inside the sandbox, the same in the dev preview as in Metab
 | `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"]}'`. The preview reads the `allowed_hosts:` list in `data_app.yaml` beside `package.json`: in a synced repository that file is the app's exported manifest, so export again and pull the export branch (`data-app`, _Move to another instance_) to refresh it rather than writing it; without one, write the list there yourself. 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.
+**External APIs.** A raw `fetch` reaches only the origins in the app's `allowed_hosts`, exact or with a `*.` subdomain wildcard, listed in `data_app.yaml` beside `package.json`:
+
+```yaml
+allowed_hosts:
+  - https://api.example.com
+```
+
+The preview reads the list there: restart `npm run dev` after changing it. Metabase applies it once the app is released (`data-app`, _Release_). 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
 
@@ -77,7 +84,7 @@ export function AppError({ message }: SdkErrorComponentProps) {
 | `StaticQuestion`      | A chart, KPI or table without drill-through — the default.                              |
 | `InteractiveQuestion` | One meant to be explored: drill-through, chart switching; pass `isSaveEnabled={false}`. |
 
-Both take a question in the app's collection. Dashboards and the authoring components (`CreateQuestion`, `CreateDashboardModal`, saving from the editor) don't work in an app: its collection can't hold a dashboard, and an app can't save content.
+Both take the `card` built from `useMetabaseQueryObject` (`data-app-data`). Dashboards and the authoring components (`CreateQuestion`, `CreateDashboardModal`, saving from the editor) don't work in an app: an app can't save content.
 
 ## A Metabase chart or your own
 
@@ -85,6 +92,7 @@ Ask "can Metabase draw this at all?", never "which looks closer to the design?"
 
 - **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 table the user picks a row from, to drive another panel, is drawn from `useMetabaseQuery` rows with a button per row: an SDK question reports no row click.
 - A KPI is `scalar`, `smartscalar`, `gauge` or `progress` — on a question filtered at runtime to one bucket, `scalar` (a `smartscalar` loses its comparison); 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.
 
@@ -120,4 +128,4 @@ Metabase mirrors each route to `/apps/<slug>/<path>`, and a reload there opens t
 
 ## 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("` (a date string parsed as UTC) in a date filter, `* 100` and `%`. Read the diagnostics feed with every panel mounted, then build and publish (`data-app`, _Build and publish_).
+`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("` (a date string parsed as UTC) in a date filter, and `* 100` or a number followed by `%` in rendered text (`grep -nE '[0-9}]\s*%'`, then skip CSS sizes such as `"100%"`). Read the diagnostics feed with every panel mounted, then release the app (`data-app`, _Release_).

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

@@ -7,7 +7,7 @@ requires: [remoteSync]
 
 # git-sync (representations ↔ instance)
 
-Metabase content (cards, dashboards, transforms, snippets, collections, …) can live in a git repo as YAML and round-trip in and out of a Metabase instance via the `git-sync` verbs. The instance is configured with a `remote-sync-*` settings block (URL, branch, token, type read-only/read-write); the CLI drives the sync tasks against `/api/ee/remote-sync/*`. Only flagged collections serialize, plus, unflagged: each data app's collection (with its app, `data_apps/<slug>/`), transforms (`remote-sync-transforms`), and snippets, data actions and glossary once the Library is synced. Everything else is local-only. Table and field metadata round-trips too, for Library-published tables in a flagged collection — see "Published table metadata" below.
+Metabase content (cards, dashboards, transforms, snippets, collections, …) can live in a git repo as YAML and round-trip in and out of a Metabase instance via the `git-sync` verbs. The instance is configured with a `remote-sync-*` settings block (URL, branch, token, type read-only/read-write); the CLI drives the sync tasks against `/api/ee/remote-sync/*`. Only flagged collections serialize, plus, unflagged: each data app's collection (with its app, `data_apps/<slug>/`, authored in the repository: `data-app`), transforms (`remote-sync-transforms`), and snippets, data actions and glossary once the Library is synced. Everything else is local-only. Table and field metadata round-trips too, for Library-published tables in a flagged collection — see "Published table metadata" below.
 
 The repo and the instance are two ends of the same state; what "push my changes" means depends on where the changes were made. If they were made **in the instance** (CLI verbs against a read-write instance — cards edited, transforms created, tables published, metadata written), "push my changes" / "save this to the repo" / "open a PR with these changes" means driving the instance's export to a branch (`stash` or `create-branch` + `export`) and opening the PR from that branch — not reconstructing the changes as files. If the workflow is **repo-first** (content YAML edited in the repo, the instance imports it), plain `git` against the repo is the way — but only in the serialized layout already there: files in paths or formats the serializer doesn't own are invisible to Metabase and never apply on import.
 
@@ -122,11 +122,9 @@ mb git-sync export-preflight --profile <n> --json   # → {has_changes, clean, c
 
 A dry run against the live remote branch, writing nothing. Read it between the state check and the export, and decide from the fields:
 
-| Answer                              | Meaning                                                                                                                                                                     | Move                                                                                                                                                                                                                                                                    |
-| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `has_changes: false`                | The remote has not moved past the last sync, or nothing has been synced yet — and then `force_push_casualties` is empty whatever the remote holds.                          | `export -m "..."` applies as-is. Don't read empty casualties on a never-synced instance as leave to `--force`.                                                                                                                                                          |
-| `has_changes: true`, `reason: null` | The remote moved on. `clean` says whether a three-way merge would apply; `conflicts` names the entities changed on both sides; `summary` counts what a merge would fold in. | `clean: true`: `export --merge -m "..."`. `clean: false`: the conflicts need the user's call between the three options under "After a `conflict` task". A plain `export` ends in a `conflict` task, and so does `stash`: its new branch starts at the moved remote tip. |
-| `reason: "history-rewritten"`       | The remote was force-pushed or rebased, so there is no merge base.                                                                                                          | Only `export --force` can push, and only with the user's explicit go-ahead; `force_push_casualties` is exactly what it would delete or overwrite.                                                                                                                       |
+- **`has_changes: false`**: the remote has not moved past the last sync, or nothing has been synced yet — and then `force_push_casualties` is empty whatever the remote holds. `export -m "..."` applies as-is. Don't read empty casualties on a never-synced instance as leave to `--force`.
+- **`has_changes: true`, `reason: null`**: the remote moved on. `clean` says whether a three-way merge would apply; `conflicts` names the entities changed on both sides; `summary` counts what a merge would fold in. `clean: true`: `export --merge -m "..."`. `clean: false`: the conflicts need the user's call between the three options under "After a `conflict` task". A plain `export` ends in a `conflict` task, and so does `stash`: its new branch starts at the moved remote tip.
+- **`reason: "history-rewritten"`**: the remote was force-pushed or rebased, so there is no merge base. Only `export --force` can push, and only with the user's explicit go-ahead; `force_push_casualties` is exactly what it would delete or overwrite.
 
 `force_push_casualties` is reported on every answer: it is the remote content a force push would discard instead of merging, so read it before ever passing `--force`. It is empty when nothing has been synced yet, yet `export --force` then replaces the remote's managed directories wholesale: check the remote before forcing a first export.
 

package/skill-data/transform/SKILL.md

@@ -271,6 +271,6 @@ mb transform-job set-active false --profile <name> --json  # disable every job a
 
 <!-- /requires -->
 
-Every job row carries `active`; it is `null` on a server that cannot switch jobs off, where every job runs on schedule.
+Every job row carries `active`; it is `null` on a server that cannot switch jobs off, where every job runs on schedule. A job with `active: false` never runs on schedule, and a fresh install of a newer server starts the built-in jobs that no transform uses that way: before relying on one, check `active`, and turn it on only with the user's yes (`transform-job update <id> --body '{"active":true}'`, admin only).
 
 `transform-job run` is fire-and-forget — it returns `{message, started, run_id}` immediately (both `null` when the server does not number job runs: the request was accepted and whether a run started is unsaid), with no per-job-run polling (no `--wait`). Most ad-hoc agent work is one-off `transform run`, not job authoring.

package/dist/api-key-Cia6SHQ9.mjs

@@ -1,13 +0,0 @@
-import { t as defineCommandGroup } from "./group-D1nGaEXW.mjs";
-//#region src/commands/api-key/index.ts
-var api_key_default = defineCommandGroup({
-	name: "api-key",
-	description: "Manage Metabase API keys",
-	subCommands: {
-		list: () => import("./list-mRSKPKoO.mjs").then((mod) => mod.default),
-		create: () => import("./create-Dm8BvbsU.mjs").then((mod) => mod.default),
-		delete: () => import("./delete-D_l7FRE6.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { api_key_default as default };

package/dist/card-C-KsmoJW.mjs

@@ -1,25 +0,0 @@
-import { t as defineCommandGroup } from "./group-D1nGaEXW.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-DAdWd8gn.mjs").then((mod) => mod.default),
-		get: () => import("./get-3XwqrjxC.mjs").then((mod) => mod.default),
-		query: () => import("./query-B4xK9j0u.mjs").then((mod) => mod.default),
-		alerts: () => import("./alerts-C7vJ-NAI.mjs").then((mod) => mod.default),
-		create: () => import("./create-C6c-clLK.mjs").then((mod) => mod.default),
-		update: () => import("./update-BGFGng3a.mjs").then((mod) => mod.default),
-		verify: () => import("./verify-BSlj7S_E.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-CuygjxgQ.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { card_default as default };

package/dist/collection-DsNRlVcN.mjs

@@ -1,21 +0,0 @@
-import { t as defineCommandGroup } from "./group-D1nGaEXW.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-CcfGHN19.mjs").then((mod) => mod.default),
-		get: () => import("./get-DvPgnqAA.mjs").then((mod) => mod.default),
-		items: () => import("./items-B1DXzdwg.mjs").then((mod) => mod.default),
-		tree: () => import("./tree-BDhm4E_W.mjs").then((mod) => mod.default),
-		create: () => import("./create-zALsdMhF.mjs").then((mod) => mod.default),
-		update: () => import("./update-DU3jpGps.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-TBPRGm7s.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { collection_default as default };

package/dist/create-D-Eu1nBe.mjs

@@ -1,37 +0,0 @@
-import { dt as outputFlags, ft as profileFlag, ot as connectionFlags, u as renderSummary } from "./cli.mjs";
-import { t as defineMetabaseCommand } from "./runtime-Dd2uBKqN.mjs";
-import { t as bodyInputFlags } from "./body-flags-AqKpN01Y.mjs";
-import { r as DataAppCreateInput, t as DataApp } from "./data-app-BUW-HlUo.mjs";
-import { t as dataAppView } from "./data-app-Blz61mG5.mjs";
-//#region src/commands/data-app/create.ts
-var create_default = defineMetabaseCommand({
-	meta: {
-		name: "create",
-		description: "Create a data app and its collection from JSON"
-	},
-	details: "The JSON body needs `name`, the slug. Optional: `display_name` (the slug by default), `description`, `allowed_hosts`, `enabled` (true by default), `bundle_path` and `version`. The app starts with an empty bundle; `mb data-app set-bundle` replaces it. The answer's `resource_collection_id` is the app's collection, where its questions and actions go. `mb data-app scaffold` copies the project template.",
-	skills: [{
-		skill: "data-app",
-		purpose: "how an app is created, built and published"
-	}],
-	requires: ["dataApp.create"],
-	args: {
-		...outputFlags,
-		...profileFlag,
-		...connectionFlags,
-		...bodyInputFlags
-	},
-	inputSchema: DataAppCreateInput,
-	outputSchema: DataApp,
-	examples: ["mb data-app create --body '{\"name\":\"sales-overview\",\"display_name\":\"Sales overview\"}'", "mb data-app create --file app.json --json"],
-	async run({ args, ctx, getClient, readBody }) {
-		const body = await readBody({
-			flag: args.body,
-			file: args.file
-		});
-		const created = await (await getClient()).dataApp.create(body);
-		renderSummary(created, dataAppView, `Created data app ${created.name} with collection ${created.resource_collection_id}.`, ctx);
-	}
-});
-//#endregion
-export { create_default as default };