@metabase/cli 0.5.2 → 0.5.4

package/dist/{validate-BQ7vI8_x.mjs → validate-moGYlHxB.mjs}

@@ -1,4 +1,4 @@
-import { Lt as escapeJsonPointerSegment, St as ConfigError, Y as isPlainObject } from "./cli.mjs";
+import { S as escapeJsonPointerSegment, o as ConfigError, r as isPlainObject } from "./predicates-0C0TsWcJ.mjs";
 import { z } from "zod";
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
@@ -1012,8 +1012,11 @@ var query_default = {
 				"lib/type": { "const": "mbql.stage/native" },
 				"native": { "type": "string" },
 				"template-tags": {
-					"type": "object",
-					"additionalProperties": { "$ref": "#/$defs/template_tag" }
+					"description": "Template tag definitions. The current format is a list of template tags (order-preserving). The legacy map format (tag name -> tag) is also accepted.\n",
+					"type": ["array", "object"],
+					"if": { "type": "array" },
+					"then": { "items": { "$ref": "#/$defs/template_tag" } },
+					"else": { "additionalProperties": { "$ref": "#/$defs/template_tag" } }
 				}
 			}
 		},
@@ -1350,23 +1353,10 @@ const refSchemaWithIds = {
 	}
 };
 const templateTag = query_default.$defs.template_tag;
-const nativeStage = query_default.$defs.native_stage;
-const TEMPLATE_TAG_REF = { $ref: "#/$defs/template_tag" };
 const querySchemaForApi = {
 	...query_default,
 	$defs: {
 		...query_default.$defs,
-		native_stage: {
-			...nativeStage,
-			properties: {
-				...nativeStage.properties,
-				"template-tags": {
-					type: ["object", "array"],
-					additionalProperties: TEMPLATE_TAG_REF,
-					items: TEMPLATE_TAG_REF
-				}
-			}
-		},
 		template_tag: {
 			...templateTag,
 			properties: {
@@ -1491,7 +1481,7 @@ function assertNotLegacyEnvelopeWrappingMbql5(value, options) {
 	if (!isLegacyEnvelopeWrappingMbql5(value)) return;
 	throw new ConfigError(`${options.contextLabel}: ${options.bodyNoun} is the query itself: {"lib/type": "mbql/query", "database": N, "stages": […]}.`);
 }
-z.object({
+const QuerySchemaBundle = z.object({
 	schema: z.unknown(),
 	defs: z.object({
 		"id.yaml": z.unknown(),
@@ -1512,4 +1502,4 @@ function getQuerySchemaBundle() {
 	};
 }
 //#endregion
-export { validateQuery as a, isMbql5Query as i, assertNotLegacyEnvelopeWrappingMbql5 as n, getQuerySchemaBundle as r, ValidationOutcome as t };
+export { isMbql5Query as a, getQuerySchemaBundle as i, ValidationOutcome as n, validateQuery as o, assertNotLegacyEnvelopeWrappingMbql5 as r, QuerySchemaBundle as t };

package/dist/validate-query-Bf5FhhMI.mjs

@@ -0,0 +1,72 @@
+import { o as ConfigError, r as isPlainObject } from "./predicates-0C0TsWcJ.mjs";
+import { f as writeJson } from "./cli.mjs";
+import { a as isMbql5Query, i as getQuerySchemaBundle, o as validateQuery, r as assertNotLegacyEnvelopeWrappingMbql5 } from "./validate-moGYlHxB.mjs";
+//#region src/commands/validate-query.ts
+const skipValidateFlag = { "skip-validate": {
+	type: "boolean",
+	description: "Skip the local MBQL 5 pre-flight validation; let the server be the authority. Use only when the bundled schema disagrees with what the server accepts."
+} };
+const QUERY_DOCUMENTS = {
+	title: "MBQL 5 query",
+	command: ["query"],
+	bundle: getQuerySchemaBundle()
+};
+function hasQuerySource(body) {
+	return valueAt(body, ["source", "type"]) === "query";
+}
+const CARD_DATASET_QUERY = {
+	resource: "card",
+	path: ["dataset_query"],
+	when: null,
+	documents: QUERY_DOCUMENTS
+};
+const DATA_ACTION_DATASET_QUERY = {
+	resource: "dataAction",
+	path: ["dataset_query"],
+	when: null,
+	documents: QUERY_DOCUMENTS
+};
+const TRANSFORM_SOURCE_QUERY = {
+	resource: "transform",
+	path: ["source", "query"],
+	when: hasQuerySource,
+	documents: QUERY_DOCUMENTS
+};
+const MEASURE_DEFINITION = {
+	resource: "measure",
+	path: ["definition"],
+	when: null,
+	documents: QUERY_DOCUMENTS
+};
+const SEGMENT_DEFINITION = {
+	resource: "segment",
+	path: ["definition"],
+	when: null,
+	documents: QUERY_DOCUMENTS
+};
+function preflightEmbeddedQuery(body, embedded, options) {
+	const holdsNoQuery = embedded.when !== null && !embedded.when(body);
+	if (options.skip || holdsNoQuery) return;
+	const query = valueAt(body, embedded.path);
+	const bodyNoun = embedded.path.join(".");
+	const contextLabel = `${embedded.resource}.${bodyNoun} validation failed`;
+	assertNotLegacyEnvelopeWrappingMbql5(query, {
+		contextLabel,
+		bodyNoun
+	});
+	if (!isMbql5Query(query)) return;
+	const outcome = validateQuery(query);
+	if (outcome.ok) return;
+	writeJson(outcome);
+	throw new ConfigError(`${contextLabel}: ${outcome.errors.length} error(s) — fix them, or pass --skip-validate to send anyway`);
+}
+function valueAt(body, path) {
+	let value = body;
+	for (const key of path) {
+		if (!isPlainObject(value)) return;
+		value = value[key];
+	}
+	return value;
+}
+//#endregion
+export { CARD_DATASET_QUERY, DATA_ACTION_DATASET_QUERY, MEASURE_DEFINITION, QUERY_DOCUMENTS, SEGMENT_DEFINITION, TRANSFORM_SOURCE_QUERY, preflightEmbeddedQuery, skipValidateFlag };

package/dist/{values-BFPO6y5o.mjs → values-CtY5zv0m.mjs}

@@ -1,8 +1,8 @@
-import { c as renderSummary, ct as outputFlags, lt as profileFlag, m as formatScalar, rt as connectionFlags } from "./cli.mjs";
-import { t as parseId } from "./parse-id-5BZGQ9Vd.mjs";
-import { t as defineMetabaseCommand } from "./runtime-Cmes70jO.mjs";
-import { u as FieldValues } from "./field-DoWQUl7V.mjs";
-import { s as fieldValuesView } from "./field-BVz4AS3f.mjs";
+import { h as formatScalar, it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
+import { t as parseId } from "./parse-id-EXZan40V.mjs";
+import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { d as FieldValues } from "./field-C2qOViFZ.mjs";
+import { s as fieldValuesView } from "./field-CT4r6b92.mjs";
 //#region src/commands/field/values.ts
 var values_default = defineMetabaseCommand({
 	meta: {

package/dist/{verify-C-StvB4f.mjs → verify-BiB8jzXB.mjs}

@@ -1,6 +1,6 @@
-import { c as renderSummary, ct as outputFlags, lt as profileFlag, rt as connectionFlags } from "./cli.mjs";
-import { t as parseId } from "./parse-id-5BZGQ9Vd.mjs";
-import { t as defineMetabaseCommand } from "./runtime-Cmes70jO.mjs";
+import { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
+import { t as parseId } from "./parse-id-EXZan40V.mjs";
+import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
 import { t as ModerationReview } from "./moderation-review-Bf9bPNQI.mjs";
 import { i as moderationReviewView, n as verifyFlags, r as describeReview, t as reviewInput } from "./verify-flags-DEVMB9w0.mjs";
 //#region src/commands/card/verify.ts

package/dist/{verify-CuGs0X3C.mjs → verify-DBTlWx-S.mjs}

@@ -1,6 +1,6 @@
-import { c as renderSummary, ct as outputFlags, lt as profileFlag, rt as connectionFlags } from "./cli.mjs";
-import { t as parseId } from "./parse-id-5BZGQ9Vd.mjs";
-import { t as defineMetabaseCommand } from "./runtime-Cmes70jO.mjs";
+import { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
+import { t as parseId } from "./parse-id-EXZan40V.mjs";
+import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
 import { t as ModerationReview } from "./moderation-review-Bf9bPNQI.mjs";
 import { i as moderationReviewView, n as verifyFlags, r as describeReview, t as reviewInput } from "./verify-flags-DEVMB9w0.mjs";
 //#region src/commands/dashboard/verify.ts

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

@@ -1,6 +1,7 @@
-import { n as createClient } from "./client-D-Aw6JLk.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 { n as createClient } from "./client-DvWllzKd.mjs";
+import { g as errorMessage, l as MetabaseError, p as TimeoutError, u as NetworkError } from "./predicates-0C0TsWcJ.mjs";
+import { K as HttpError } from "./cli.mjs";
+import { B as probeServer, E as USER_AGENT } from "./runtime-iIsqiOwO.mjs";
 //#region src/core/auth/verify.ts
 const VERIFY_TIMEOUT_MS = 15e3;
 async function verifyAndProbe(url, credential, options = {}) {

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

@@ -1,9 +1,9 @@
-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 { 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 { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
+import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-vxN__4cz.mjs";
+import { r as parseWaitSchedule } from "./wait-flags-C3cu_O0w.mjs";
 import { u as syncTaskView } from "./git-sync-D1aKczo6.mjs";
-import { a as throwIfFailedTask, i as taskPollOptions, n as formatSyncTask, r as syncTaskIdleView, t as SyncTaskOrIdle } from "./sync-task-DNKG9Bk4.mjs";
+import { a as throwIfFailedTask, i as taskPollOptions, n as formatSyncTask, r as syncTaskIdleView, t as SyncTaskOrIdle } from "./sync-task-Gf86CU9l.mjs";
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;
 var wait_default = defineMetabaseCommand({

package/dist/{wait-flags-BnZ-dfE2.mjs → wait-flags-C3cu_O0w.mjs}

@@ -1,6 +1,6 @@
 import { t as interruptSignal } from "./cli.mjs";
-import { t as parseId } from "./parse-id-5BZGQ9Vd.mjs";
-import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-CgtcJopL.mjs";
+import { t as parseId } from "./parse-id-EXZan40V.mjs";
+import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-vxN__4cz.mjs";
 //#region src/commands/wait-flags.ts
 const waitScheduleFlags = {
 	timeout: {

package/dist/{window-CfK_j6m1.mjs → window-D1w7B0vh.mjs}

@@ -1,4 +1,4 @@
-import { g as projectForList } from "./cli.mjs";
+import { _ as projectForList } from "./cli.mjs";
 //#region src/output/window.ts
 const MAX_REQUEST_PAGE_SIZE = 200;
 function windowList(items, range, serverTotal) {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@metabase/cli",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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

@@ -1,6 +1,6 @@
 ---
 name: core
-description: Foundations for driving Metabase from the terminal with the `mb` CLI — authentication and named profiles, the flag/output/`--json` conventions every command shares, JSON body input, command discovery via `--help` (add `--json` for machine-readable schemas), and the per-resource footguns (db, table, field, upload, content translation, card, dashboard, collection, segment, measure, timeline, alert, subscription, library, setting, search, eid). Load first for any `mb` task; it routes to the specialized skills for deeper work.
+description: Foundations for driving Metabase from the terminal with the `mb` CLI — authentication and named profiles, the flag/output/`--json` conventions every command shares, JSON body input, command discovery via `--help` and `mb schema`, and the per-resource footguns (db, table, field, upload, content translation, card, dashboard, collection, segment, measure, timeline, alert, subscription, library, setting, search, eid). Load first for any `mb` task; it routes to the specialized skills for deeper work.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -13,10 +13,10 @@ 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 | schema
 ```
 
-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.
+The conventions below — auth, flags, output, body input — hold across **every** group. 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 SQL when MBQL can't express it.
 
 ## Auth & profiles
 
@@ -28,13 +28,13 @@ mb auth status --json                    # → {profile, present, url} for the d
 mb auth status --profile <name> --json   # health probe for one profile
 ```
 
-`auth list` is the primary enumeration path — one call returns every profile with sanitized URL, an `authenticated` flag, and a probe `status` (`ok` / `auth-failed` / `network-error` / `server-error` / `not-probed`). Use it before asking which profile to pick.
+`auth list` returns every profile in one call, with sanitized URL, an `authenticated` flag, and a probe `status` (`ok` / `auth-failed` / `network-error` / `server-error` / `not-probed`). Use it before asking which profile to pick.
 
 - One profile and intent doesn't disambiguate → use it.
 - Several → ask via `AskUserQuestion`, presenting the names from `auth list`.
 - Empty `data: []` → ask the user to run `mb auth login` themselves and tell you the profile name.
 
-Once a name is established, pass `--profile <name>` to **every** subsequent command. Profile names are arbitrary local labels (`prod`, `staging`).
+Profile names are arbitrary local labels (`prod`, `staging`).
 
 ## Flag conventions
 
@@ -46,7 +46,7 @@ Once a name is established, pass `--profile <name>` to **every** subsequent comm
 ❌ mb table --profile prod list  # → unknown command: prod
 ```
 
-**`--wait` for async operations.** `transform run`, `git-sync import`, and similar verbs return immediately by default. Pass `--wait` whenever the next step depends on completion — without it you race the operation and see "not ready" / transient connection refusals.
+**`--wait` for async operations.** `transform run`, `git-sync import`, and similar verbs return immediately; pass `--wait` whenever the next step depends on completion — without it you race the operation and see "not ready" / transient connection refusals.
 
 **Some "lookup" verbs return JSON envelopes, not bare values.** `mb setting get <key>` returns `{"key": "...", "value": ...}`. Extract before reusing:
 
@@ -94,7 +94,7 @@ Verbs that take a payload accept it from one of four sources, **first non-empty
 3. stdin (auto-detected when piped; `--file -` names it explicitly)
 4. positional argument
 
-Exactly one required; passing more than one of `--body` / `--file` / a positional argument is rejected with a `ConfigError`.
+Exactly one; more than one of `--body` / `--file` / a positional argument is a `ConfigError`.
 
 ```bash
 cat > ./.scratch/body.json <<'EOF'
@@ -105,7 +105,7 @@ mb <noun> create --file ./.scratch/body.json --profile <n> --json
 
 Single-quoted `'EOF'` stops the shell interpolating `$vars` inside the JSON.
 
-Write working files to **`./.scratch`** in the current directory (`mkdir -p ./.scratch` first), never `/tmp` — better permissions, they persist across the session, and the user can review them.
+Write working files to **`./.scratch`** in the current directory (`mkdir -p ./.scratch` first), never `/tmp`: better permissions, kept for the session, reviewable by the user.
 
 ## Discovering commands and schemas
 
@@ -113,12 +113,13 @@ Cheapest source that answers the question wins:
 
 - What groups/verbs exist? → `mb --help`, then `mb <group> --help`. Add `--json` for a machine-readable `{command, description}` index (`mb --help --json` lists every command).
 - What flags does a command take? → `mb <command> --help` — flags with enums and defaults, examples, ~1 KB.
-- Output JSON Schema before parsing, JSON-body input schema before authoring, machine-readable arg types, min server version? → `mb <command> --help --json` — that command's full entry (`inputSchema` is the exact validator the command runs on the body; `null` when it takes none).
+- Body shape before authoring, output before parsing? → `mb schema <command>`: the body's JSON Schema, a feature a field needs in its `description`; `--output` for output.
+- Flags, arg types, needed features? → `mb <command> --help --json`.
 
 ```bash
 mb card query --help                                    # flags, enums, defaults, examples
-mb card list --help --json | jq .outputSchema           # output schema before parsing
-mb card create --help --json | jq .inputSchema          # body schema before authoring
+mb schema card create                                   # body schema before authoring
+mb schema card list --output                            # output schema before parsing
 mb transform --help --json | jq -r '.commands[].command'  # verbs under "transform"
 ```
 
@@ -152,7 +153,7 @@ What `--help` doesn't say: footguns and non-obvious behaviors.
 <!-- requires: transforms -->
 - **transform.** Iterate with `transform update <id>`, never `delete` + `create` (keeps the row, `entity_id`, materialized table, and YAML filename — avoids `_2` suffixes and noisy git history). `transform run` needs `--wait` (or `--sync`, which also waits for the output table to register and returns `target_table_id`) or you get only `{run_id, final:null}`. (→ `transform`.)
 <!-- /requires -->
-- **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only — errors against an already-configured one. Mostly for bootstrapping local / e2e instances.
+- **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only and errors on a configured one; mostly for bootstrapping local / e2e instances.
 - **eid** translates a string entity id → numeric id: `mb eid --model <model> <eid1,eid2> --json`. Entity ids are NanoIDs that can start with `-`, which the positional form misreads as a flag (shell quotes don't help) — for those, use `--body '{"entity_ids":{"card":["-…"]}}'` (the id is a JSON string value, immune to flag parsing).
 <!-- requires: library -->
 - **library.** The Library is a curated subtree (`library-data` "Data" + `library-metrics` "Metrics" under a `library` root): tables in **Data** lead data pickers and rank up in search; metrics in **Metrics** lead nav, search, and the query builder. `library get` shows its Data/Metrics collection ids; `library create` provisions it (idempotent). `library publish --table-ids/--db-ids/--schemas` publishes tables into Data, **resolving the Data collection and creating the Library if absent**; each `--schemas` entry is `<db-id>:<schema>` (`1:public`), not a bare name. `publish` cascades to upstream FK dependencies, `unpublish` to downstream dependents; both need **admin or data-analyst** (Curate alone won't publish) and exit **403** without write **and** query permission on every affected table. `table get`/`table list` carry `is_published` (`collection_id` under `--full`). Publishing leaves the Data collection out of git-sync scope: on a remote-sync instance, `mb git-sync add-collection <data-collection-id>` makes exports carry published tables' metadata (see `git-sync`).
@@ -164,7 +165,7 @@ What `--help` doesn't say: footguns and non-obvious behaviors.
 
 ## Specialized skills (load on demand)
 
-This file is enough for any single-command task. For anything deeper, load the relevant skill **proactively** — don't wing an MBQL body, a transform body, or the git-sync workflow from this overview. Load via `mb skills get <name>`.
+This file is enough for any single-command task. For anything deeper, load the relevant skill **proactively** with `mb skills get <name>` — don't wing an MBQL body, a transform body, or the git-sync workflow from this overview.
 
 - **`mbql`** — authoring/fixing any MBQL query body (`mb query`, card `dataset_query`, transform `source.query`, measure/segment `definition`); reading `--dry-run` errors. The query-body reference.
 - **`native-sql`** — authoring a native SQL `dataset_query` with parameters: template tags, field filters vs. raw variables, snippets, card references, and wiring a tag to a dashboard filter. The SQL fallback when MBQL can't express it (`mbql` first).

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",
+};