@metabase/cli 0.5.1 → 0.5.3

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 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]
 ---
@@ -13,17 +13,27 @@ Flag conventions and `./.scratch` are in `core`; the native query and its templa
 
 ## Check the database first
 
-Data actions are off on every database until an admin turns on **Model actions** for it (Admin → Databases → the database). `mb` cannot change that setting.
+Data actions are off on every database until an admin turns on **Data actions** for it ("Allow data actions that use this database to be run", Admin → Databases → the database). That toggle is the database setting `database-enable-actions`.
 
 ```bash
 mb db get <id> --full --json
 ```
 
 - `features` must contain `"actions"` — otherwise the driver cannot run writes; pick another database.
-- `settings["database-enable-actions"]` must be `true`. If it is not, ask the user to have an admin enable it. Create and execute fail with `Actions are not enabled.` until then.
+- `settings["database-enable-actions"]` must be `true`. Create and execute fail with `Actions are not enabled.` until then. An admin profile turns it on with `mb db set-data-actions <id> true`; anyone else asks an admin to. Turning it on lets anyone with access to the database's actions write to it, so confirm with the user first.
+
+## Pick the collection
+
+A data action goes in a data actions collection, a data app collection, or the data actions root (omit `collection_id`). A regular collection is refused with `An action without a model can only go in a data actions or data app collection.` Make one with:
+
+```bash
+mb collection create --namespace data-actions --body '{"name":"Order actions"}' --json
+```
 
 ## The body
 
+Mint one template-tag `id` per tag with `mb uuid --count <n> --format text`.
+
 ```json
 {
   "name": "Set order note",
@@ -39,14 +49,14 @@ mb db get <id> --full --json
         "native": "UPDATE orders SET note = {{note}} WHERE id = {{order_id}}",
         "template-tags": {
           "order_id": {
-            "id": "order_id",
+            "id": "6f1c9a4e-2b7d-4e0a-9c3f-1d2e3f4a5b6c",
             "name": "order_id",
             "display-name": "Order ID",
             "type": "number",
             "required": true
           },
           "note": {
-            "id": "note",
+            "id": "0b8d7c6e-5f4a-4b3c-8d2e-1f0a9b8c7d6e",
             "name": "note",
             "display-name": "Note",
             "type": "text",
@@ -78,7 +88,8 @@ mb db get <id> --full --json
 ```
 
 - `type` is always `"query"`. Never set `model_id` or `type: "implicit"`; `mb data-action create` refuses both.
-- `database_id` and `dataset_query.database` are the same id (`mb db list`). Omit `collection_id` for the root collection (`mb collection list`).
+- `database_id` and `dataset_query.database` are the same id (`mb db list`). `collection_id` is the data actions collection (here `12`); omit it for the data actions root.
+- A template tag's `id` is a UUID, unique among the tags: the representation schema requires one.
 - One statement, no `;`. `create` and `update` validate `dataset_query` as `native-sql` does.
 
 ## Parameters: one per template tag
@@ -92,7 +103,7 @@ Each `{{name}}` needs a `template-tags` entry and a `parameters` entry, all usin
 | `date`     | `date/single`    |
 | `boolean`  | `boolean/=`      |
 
-- Parameter `id` and `slug` are the tag name; `target` is `["variable", ["template-tag", "<name>"]]`.
+- Parameter `id` and `slug` are the tag name (not the tag's UUID `id`); `target` is `["variable", ["template-tag", "<name>"]]`.
 - Use raw variables only. A field filter (`type: "dimension"`), snippet or card reference does not work in a write — write the comparison yourself (`WHERE id = {{order_id}}`).
 - Set `required: true` on every input the statement cannot run without (`WHERE` keys, `NOT NULL` columns).
 - Wrap an optional input in `[[ … ]]` with `required: false`; the clause drops out when no value is given. This makes one action do partial updates: `UPDATE orders SET updated_at = now() [[, note = {{note}}]] [[, status = {{status}}]] WHERE id = {{order_id}}`.

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