@metabase/cli 0.5.2 → 0.5.3

package/dist/{verify-7fW020r_.mjs → verify-crIrbGZV.mjs}

@@ -1,6 +1,6 @@
-import { n as createClient } from "./client-D-Aw6JLk.mjs";
+import { n as createClient } from "./client-BFP2Ssqu.mjs";
 import { Et as NetworkError, Mt as errorMessage, Tt as MetabaseError, W as HttpError, kt as TimeoutError } from "./cli.mjs";
-import { B as probeServer, T as USER_AGENT } from "./runtime-Cmes70jO.mjs";
+import { B as probeServer, T as USER_AGENT } from "./runtime-Y4VFWmmr.mjs";
 //#region src/core/auth/verify.ts
 const VERIFY_TIMEOUT_MS = 15e3;
 async function verifyAndProbe(url, credential, options = {}) {

package/dist/{wait-Cvt8xO0h.mjs → wait-mFUfpSaj.mjs}

@@ -1,5 +1,5 @@
 import { c as renderSummary, ct as outputFlags, lt as profileFlag, rt as connectionFlags } from "./cli.mjs";
-import { t as defineMetabaseCommand } from "./runtime-Cmes70jO.mjs";
+import { t as defineMetabaseCommand } from "./runtime-Y4VFWmmr.mjs";
 import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-CgtcJopL.mjs";
 import { r as parseWaitSchedule } from "./wait-flags-BnZ-dfE2.mjs";
 import { u as syncTaskView } from "./git-sync-D1aKczo6.mjs";

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@metabase/cli",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Metabase CLI",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/metabase/mb-cli.git",
+    "url": "git+https://github.com/metabase/metabase-cli.git",
     "directory": "packages/cli"
   },
   "bin": {

package/skill-data/core/SKILL.md

@@ -13,7 +13,7 @@ Top-level command groups (run `mb <group> --help` to discover verbs):
 ```
 auth | db | table | field | upload | content-translation | query | card | dashboard | snippet | segment | measure | collection | library
 document | glossary | timeline | timeline-event | transform | transform-job | transform-tag | transform-test | alert | subscription | setting
-search | dependency | git-sync | data-action | setup | eid | uuid | upgrade | skills
+search | dependency | git-sync | data-action | data-app | setup | eid | uuid | upgrade | skills
 ```
 
 The conventions below — auth, flags, output, body input — hold across **every** group. Per-command flags and examples live in each command's `--help`; add `--json` for the machine-readable form with the output JSON Schema. A few flows have their own skills (see "Specialized skills"). When a card needs a query, prefer MBQL over native SQL (portable, pre-flight-validated — load `mbql`); fall back to native SQL when MBQL can't express it.

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

@@ -1,6 +1,6 @@
 ---
 name: data-action
-description: Author and run Metabase data actions with the `mb` CLI — saved, parameterized native SQL writes (INSERT, UPDATE, DELETE) filed in a collection and run with values. Covers enabling them on a database, the collection they go in, the body, mapping template tags to parameters, running, and the lifecycle. Triggers — "add a data action", "let users update a row", "a button that inserts a record", "run a write query", "a form that saves to the database", "delete rows from Metabase".
+description: Author and run Metabase data actions with the `mb` CLI — saved, parameterized native SQL writes (INSERT, UPDATE, DELETE) filed in a collection and run with values. Covers enabling them on a database, the collection they go in, the body, mapping template tags to parameters, running, and the lifecycle. Triggers — "add a data action", "let users update a row", "a button that inserts a record", "run a write query", "a form that saves to the database", "delete rows from Metabase". Inside a data app, start with `data-app-actions`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 requires: [dataActionsWithoutModel]
 ---

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

@@ -0,0 +1,138 @@
+---
+name: data-app
+description: Create, preview, publish and manage a Metabase data app — a React app Metabase serves at /apps/<slug> — create it, scaffold its project, run the dev preview and read its diagnostics feed, build and publish the bundle, turn it on or off, move it to another instance, delete it. Triggers — "build a data app", "make an internal tool in Metabase", "scaffold a data app", "publish my data app", "update the app", "the app is blank". Start here; the UI is in `data-app-ui`, questions and charts in `data-app-data`, filter controls in `data-app-filters`, writes in `data-app-actions`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+requires: [dataApps]
+---
+
+# Data apps
+
+A **data app** is a React app built into one JavaScript bundle, which Metabase runs in a sandbox at `/apps/<slug>`. Each app has its own collection — **the app's collection** — and the questions and actions in it are everything the app can run. Flag conventions are in `core`.
+
+The work, in order:
+
+1. Create the app on the instance.
+2. Scaffold the project and install the SDK.
+3. Give it data: questions over the Library's published tables and metrics in the app's collection, then `src/metabase.ts` (`data-app-data`); writes are `data-app-actions`.
+4. Start the dev preview (_Dev preview_), then write the UI under `src/` (`data-app-ui`; filter controls in `data-app-filters`).
+5. Build and publish (_Build and publish_).
+
+For every later change: regenerate `src/metabase.ts` if the app's collection changed, then build and set the bundle. Metabase receives only the built bundle; the source stays in the project directory, under git if the user keeps one.
+
+## Before you start
+
+- Use an **admin** profile — only admins create apps and write the app's collection. `mb auth status --json | jq .user.isAdmin` prints `true` for one; otherwise ask the user for an admin profile (`mb auth list`).
+- Run `mb data-app list`. A failure means the instance has no data apps: stop and tell the user.
+- Settle the **slug**, the `/apps/<slug>` URL: lowercase letters, digits and single dashes (`sales-overview`), at most 100 characters. If the app's purpose is unclear, ask "what's this app for?" and propose one.
+
+## Create the app
+
+```bash
+mb data-app create --body '{"name":"sales-overview","display_name":"Sales overview"}' --json
+```
+
+`name` is the slug; `display_name` and `description` are optional. The app starts disabled, with an empty bundle. The answer's `resource_collection_id` is the id of the app's collection — note it. A `409` means the slug is taken: `mb data-app list` shows that app; reuse it or pick another slug.
+
+## Scaffold and install
+
+```bash
+mb data-app scaffold sales-overview && cd sales-overview
+```
+
+`scaffold [dir]` takes a **directory**, not the slug: it copies the Vite + React + TypeScript template into a new or empty directory (the current one when omitted) and needs no server. Then install the SDK, then the rest:
+
+```bash
+npm install @metabase/embedding-sdk-react@<major>-beta   # <major>: 66 for a version tag v1.66.x (`mb auth status --json | jq -r .version.tag`)
+npm install && npm run typecheck && npm run build
+```
+
+Skip the SDK line when `package.json` already points it at a local build (`file:` or `link:`), and never install `latest`. A tag without a version number, such as `vLOCAL_DEV`, is a development build: ask the user which SDK build to install. The starter renders "Hello, data app".
+
+The template is the bundle contract. Don't edit `package.json` by hand, and never rewrite `vite.config.ts`, `tsconfig.json` or `src/index.tsx`: `vite.config.ts` stays `export default dataAppConfig()` (its only option is `port`), and `src/index.tsx` default-exports the `DataAppFactory` — change it only to add a `providerProps` key. Metabase and the dev preview each wrap the app in a `<MetabaseProvider>`, so the app never renders one.
+
+**An existing project.** Before changing an app you didn't scaffold in this session, check both: `vite.config.ts` is `export default dataAppConfig()` from `@metabase/embedding-sdk-react/data-app-dev/config`, with no local `config/` directory; and `src/index.tsx` default-exports a `DataAppFactory` that takes no arguments and returns `{ component, providerProps? }`. If either fails, stop: tell the user the project differs from the template, and ask whether to scaffold a fresh project and port the code over, or go on at their own risk.
+
+## Dev preview
+
+`npm run dev` serves the app at `http://localhost:5174` — or the next free port, in Vite's `Local:` line — through the same sandbox Metabase uses. An edit under `src/` rebuilds the bundle and remounts the app, resetting component state. The preview reads `DATA_APP_MB_URL` and an admin `DATA_APP_MB_API_KEY` from `.env.local` beside `package.json`. Write a new key straight into that file, never into the chat or the terminal:
+
+```bash
+( umask 077
+  URL=$(mb auth status --json | jq -r .url)
+  KEY=$(mb api-key create --body '{"name":"data-app <slug> dev","group_id":2}' --json | jq -r .unmasked_key)
+  [ -n "$KEY" ] && [ "$KEY" != null ] && printf 'DATA_APP_MB_URL=%s\nDATA_APP_MB_API_KEY=%s\n' "$URL" "$KEY" > .env.local && echo written )
+```
+
+Group `2` is Administrators. Never print `.env.local`. Delete the key at handoff (`mb api-key list`, then `mb api-key delete <id> --yes`); the next session writes a new one. A CORS error means the instance doesn't allow the preview's origin: ask the user to add `http://localhost:5174` under Admin → Embedding → Embedded analytics SDK → CORS.
+
+### The diagnostics feed
+
+Sandbox blocks, failed queries and uncaught errors never reach the terminal. With a preview tab open, read them from the feed:
+
+```bash
+curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"
+```
+
+```jsonc
+{
+  "entries": [
+    {
+      "eventId": 31,
+      "kind": "blocked-network",
+      "alert": true,
+      "summary": "Blocked fetch to api.example.com (not in allowed_hosts)",
+      "detail": null,
+      "hint": "…",
+      "buildId": 7,
+    },
+  ],
+  "clients": 1, // open preview tabs; 0 means nothing ran
+  "buildId": 7, // the bundle running now
+  "staleEntries": 164, // withheld: reported by a build already replaced
+  "nextEventId": 32, // pass back as ?startEventId=
+}
+```
+
+- `clients: 0` means no tab is open, so empty `entries` prove nothing.
+- Before an edit, note `nextEventId`; after it, read again with that value as `startEventId`.
+- The feed answers for the running bundle: entries from replaced builds are counted in `staleEntries`, and anything still broken reports again under the new `buildId` (`?includeStale=true` shows the withheld ones). A failed build doesn't advance `buildId` and doesn't reach the feed — read the `npm run dev` terminal.
+- Quote `summary` as it is when you report it, and follow `hint` when there is one — except that you never add the Metabase URL to `allowed_hosts`. The feed keeps the last 200 entries; `curl -X DELETE …/__data-app/diagnostics` clears it.
+
+| `kind`                             | Fix                                                                                                                 |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `blocked-network`, `csp-violation` | An external API: `data-app-ui`, _External APIs_. A `script-src` or `style-src` violation: bundle the asset instead. |
+| `blocked-api`                      | Blocked in Metabase too: use the replacement in `data-app-ui`.                                                      |
+| `sdk-call` with `alert: true`      | A Metabase request failed; `summary` names it.                                                                      |
+| `error`                            | A bug; `detail` has the stack.                                                                                      |
+
+## Build and publish
+
+```bash
+npm run typecheck && npm run build
+mb data-app set-bundle sales-overview
+mb data-app set-enabled sales-overview true   # the first time
+```
+
+`set-bundle` uploads `dist/index.js` (`--bundle` for another path) and replaces the app's bundle, live at once. A new app is disabled until `set-enabled` turns it on. Give the user `<metabase-url>/apps/<slug>`.
+
+Admins open every app, enabled or not. Anyone else needs the app enabled (otherwise "not found") and one of their groups assigned to it (otherwise "You don't have access"), which only the user can do (Admin → Settings → Data apps → the app → Groups). A group reaches the app's collection and nothing more, so a viewer also needs data access to the tables its questions read.
+
+## Pitfalls
+
+| Symptom                                                             | Fix                                                                                                                    |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `set-bundle`: bundle not found                                      | Run `npm run build` in the project directory first.                                                                    |
+| Blank app, `Bundle did not assign a function to __dataAppFactory__` | `src/index.tsx` must `export default` the factory and nothing else; otherwise the diagnostics feed has the real error. |
+| "Failed to fetch the user, the session might be invalid."           | A bad key in `.env.local`, or CORS (_Dev preview_).                                                                    |
+| A bundle of several MB                                              | `vite.config.ts` no longer uses `dataAppConfig()`, or the SDK isn't the `<major>-beta` tag.                            |
+| "Invalid hook call"                                                 | A second React got bundled: nothing may add another `react` or `react-dom`.                                            |
+| Drill-through popups don't open                                     | The app renders its own `<MetabaseProvider>`: remove it.                                                               |
+| A rebuilt or reinstalled SDK still behaves like the old one         | Vite caches it: stop `npm run dev`, delete `node_modules/.vite`, start again.                                          |
+| A viewer's query or action fails with 403                           | It reads something outside the app's collection, or the viewer lacks data access to its tables.                        |
+
+## Change, move, delete
+
+- **Turn off:** `mb data-app set-enabled <slug> false`. **Rename:** `mb data-app update <slug> --body '{"display_name":"…"}'` (also `description`, `allowed_hosts`).
+- **Outdated:** an app Metabase lists as _Outdated_ targets an older data-app contract: it won't open for anyone, and only admins see it listed, until it's migrated. Tell the user; don't change its code ad hoc.
+- **Move to another instance:** the app, its collection and what the collection holds are git-synced content. `mb git-sync export` (`git-sync`) writes `data_apps/<slug>/` with the bundle, and the collection under `collections/data_apps/`; importing the repository on the other instance recreates them with the same entity IDs, so the same `src/metabase.ts` and bundle work there. On a read-only instance the app's collection can't be edited: change it where it was built and export again.
+- **Delete:** confirm with the user, then `mb data-app delete <slug> --yes` — it removes the app, its bundle, its collection and the questions and actions in it. The project directory stays.

package/skill-data/data-app/template/.env.local.example

@@ -0,0 +1,2 @@
+DATA_APP_MB_URL=http://localhost:3000
+DATA_APP_MB_API_KEY=mb_replace_me

package/skill-data/data-app/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Metabase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skill-data/data-app/template/README.md

@@ -0,0 +1,29 @@
+# Data app
+
+A Metabase data app: a single-bundle React app, built with the Embedding SDK,
+that Metabase serves at `/apps/<slug>`. Build and change it with a coding agent
+and the `mb` data-app skills.
+
+## Install
+
+Install the SDK tag matching the Metabase instance first, then the rest.
+`<major>` is 66 for a version tag v1.66.x (`mb auth status --json | jq -r .version.tag`);
+`package.json` asks for any version, which would install `latest`.
+
+```bash
+npm install @metabase/embedding-sdk-react@<major>-beta
+npm install
+```
+
+## Commands
+
+```bash
+npm run dev         # preview at http://localhost:5174, in the sandbox Metabase runs apps in
+npm run typecheck   # type-checks src/ and vite.config.ts
+npm run build       # builds dist/index.js
+mb data-app typed-schema <slug> --out src/metabase.ts   # the app's queries and actions
+mb data-app set-bundle <slug>                     # makes dist/index.js the app's bundle
+```
+
+`npm run dev` reads `DATA_APP_MB_URL` and `DATA_APP_MB_API_KEY` from
+`.env.local`; `.env.local.example` lists them.

package/skill-data/data-app/template/gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+.env.local
+.vite
+.idea

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

@@ -0,0 +1,25 @@
+{
+  "name": "data-app-template",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@metabase/embedding-sdk-react": "*",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^6.0.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "vite-plugin-svgr": "^5.2.0"
+  }
+}

package/skill-data/data-app/template/src/App.tsx

@@ -0,0 +1,9 @@
+export default function App() {
+  return (
+    <div style={{ minHeight: "100vh", boxSizing: "border-box", padding: 24 }}>
+      <h1 style={{ margin: 0 }}>Hello, data app</h1>
+
+      <p style={{ color: "#555" }}>Edit src/App.tsx to begin.</p>
+    </div>
+  );
+}

package/skill-data/data-app/template/src/index.tsx

@@ -0,0 +1,14 @@
+import type { DataAppFactory } from "@metabase/embedding-sdk-react/data-app";
+
+import App from "./App";
+import { sdkTheme } from "./theme";
+
+// The data app's entry point. Return the root component plus any `providerProps`
+// the host should apply to `MetabaseProvider` (e.g. `theme`,
+// `allowedCustomVisualizations`).
+const factory: DataAppFactory = () => ({
+  component: App,
+  providerProps: { theme: sdkTheme },
+});
+
+export default factory;

package/skill-data/data-app/template/src/theme.ts

@@ -0,0 +1,25 @@
+import type { MetabaseTheme } from "@metabase/embedding-sdk-react";
+
+export const sdkTheme: MetabaseTheme = {
+  colors: {
+    brand: "#4D96FF",
+    "brand-hover": "#EAF4FF",
+    positive: "#4D96FF",
+    charts: [
+      "#4D96FF",
+      "#E8743B",
+      "#2BA672",
+      "#9461D9",
+      "#E0475B",
+      "#1C9FB8",
+      "#C99A1E",
+      "#5468D4",
+    ],
+    background: "white",
+    "background-secondary": "white",
+    "text-primary": "#1f2937",
+    "text-secondary": "#4b5563",
+    "text-tertiary": "#6b7280",
+  },
+  fontFamily: "system-ui, -apple-system, Segoe UI, sans-serif",
+};

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_).