Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Added a `metabase-data-app-migrate` skill that helps upgrading data apps between versions (#82895)

Timofey Kachalovc15980048efa
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
index b8e0b19b817..44c8e8f31b3 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/config_test.clj
@@ -1,5 +1,6 @@
(ns metabase-enterprise.data-apps.config-test
(:require
+ [clojure.java.io :as io]
[clojure.test :refer :all]
[metabase-enterprise.data-apps.config :as data-app.config]))
@@ -36,6 +37,15 @@ path: ./dist/index.js"))))
(is (= data-app.config/supported-app-version
(:version (parse (slurp "skills/metabase-data-app-setup/template/data_app.yaml")))))))
+(deftest migration-upgrade-guides-cover-every-version-test
+ (testing "the migrate skill ships one guide per upgrade up to the supported version, so an app at any older version has a path"
+ (let [upgrades (->> (.listFiles (io/file "skills/metabase-data-app-migrate/references/upgrades"))
+ (keep #(re-matches #"v(\d+)-to-v(\d+)\.md" (.getName ^java.io.File %)))
+ (map (fn [[_ from to]] [(parse-long from) (parse-long to)]))
+ sort)]
+ (is (= (map (fn [n] [n (inc n)]) (range 1 data-app.config/supported-app-version))
+ upgrades)))))
+
(deftest outdated-test
(testing "an app below the supported version is outdated; one at it is not"
(with-redefs [data-app.config/supported-app-version 2]
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSkillsSection/DataAppSkillsSection.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSkillsSection/DataAppSkillsSection.tsx
index c64b39d702e..f156c2ed692 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSkillsSection/DataAppSkillsSection.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSkillsSection/DataAppSkillsSection.tsx
@@ -20,6 +20,7 @@ const DATA_APP_SKILLS = [
"metabase-data-app-routing",
"metabase-data-app-actions",
"metabase-data-app-semantic-layer",
+ "metabase-data-app-migrate",
];
export const DataAppSkillsSection = () => {
diff --git a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSkillsSection/DataAppSkillsSection.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSkillsSection/DataAppSkillsSection.unit.spec.tsx
index b82536de749..e60e8ff477f 100644
--- a/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSkillsSection/DataAppSkillsSection.unit.spec.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/data_apps/admin/components/DataAppSkillsSection/DataAppSkillsSection.unit.spec.tsx
@@ -31,6 +31,7 @@ const DATA_APP_SKILLS = [
"metabase-data-app-routing",
"metabase-data-app-actions",
"metabase-data-app-semantic-layer",
+ "metabase-data-app-migrate",
];
describe("DataAppSkillsSection", () => {
diff --git a/skills/metabase-data-app-migrate/SKILL.md b/skills/metabase-data-app-migrate/SKILL.md
new file mode 100644
index 00000000000..f368170018c
--- /dev/null
+++ b/skills/metabase-data-app-migrate/SKILL.md
@@ -0,0 +1,189 @@
+---
+name: metabase-data-app-migrate
+description: Migrate an existing Metabase data app that Metabase marks Outdated (its `data_app.yaml` `version` is below the data-app contract version the installed skills and SDK target) to the current version, one upgrade at a time, with a resumable procedure. Use when Metabase shows an app as Outdated, `npm run typecheck` or `npm run build` fails after an SDK upgrade, or an existing app's `version` is behind the one the installed skills target. Not for creating an app.
+---
+
+# Migrate a data app to the current contract version
+
+A data app declares the contract version its code targets in `data_app.yaml`
+(`version: N`; a manifest without the field is version 1). Metabase bumps the
+version it serves only on a breaking change to that contract: the
+`@metabase/embedding-sdk-react/data-app` API, the bundle factory, the manifest,
+the `queries/` and `actions/` conventions, or what an app may declare. An app on
+an older version is marked _Outdated_ in the admin list, hidden from every other
+user, and refuses to open until it is migrated.
+
+Migration is a walk over **upgrades**: `N -> N+1 -> ... -> M`, one upgrade at a time,
+each described by a guide in `references/upgrades/`. Nothing is skipped and nothing
+is remembered between sessions: the app's own files and git history carry all
+the state.
+
+## Four invariants
+
+Every step below follows from these. Never break them.
+
+1. **`version` is written last.** An upgrade's `version: N+1` goes into
+ `data_app.yaml` only after every check of that upgrade passes.
+2. **One commit per upgrade, locally.** Push only after the final gates at the
+ target version pass. The version line never moves by more than one per commit.
+3. **Compiler and build gates run only at the target version.** The installed
+ SDK is the target, so an app halfway through several upgrades cannot type-check
+ or build. Do not run them earlier and do not "fix" their failures earlier.
+4. **Nothing generated is edited by hand.** `savedQuestionSourceId`,
+ `copiedActionId`, `resources_metadata.json`, and `dist/` are written by
+ `npm run build` (`sync-resources`), never by you.
+
+## Step 0 - Locate the app and read its state
+
+Work from the app directory, `<repo>/data_apps/<slug>/`. Resolve the repo root
+with `ROOT="$(git rev-parse --show-toplevel)"`. The final build needs the
+repo-root `.env.local` credentials (`DATA_APP_MB_URL`, `DATA_APP_MB_API_KEY`).
+Check them by sourcing the file in a subshell and printing only whether both are
+set; never print the file or its variables. The key must belong to an admin:
+the API returns `version` and `outdated` only to admins and refuses an outdated
+app's metadata to everyone else, so a non-admin key cannot prove anything here.
+
+`npm` below stands for the app's own package manager, the one whose lockfile is
+committed (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`).
+Never introduce a second lockfile.
+
+Read three numbers:
+
+```bash
+# version committed at HEAD (absent line means 1)
+git show HEAD:data_apps/<slug>/data_app.yaml | grep -E '^version:' || echo "version: 1"
+# version in the working tree
+grep -E '^version:' data_app.yaml || echo "version: 1"
+# target: the highest upgrade guide shipped with this skill (no guides means 1)
+ls <skill-dir>/references/upgrades/ | sed -nE 's/^v[0-9]+-to-v([0-9]+)\.md$/\1/p' | sort -n | tail -1 | grep . || echo 1
+```
+
+`<skill-dir>` is the directory this SKILL.md was loaded from. The target must
+equal the `version:` in the data-app scaffolding template installed alongside
+this skill (`<skills-dir>/*/template/data_app.yaml`), when one is present; if
+they differ, the skills come from different Metabase releases. **Stop** and tell
+the user to reinstall all data-app skills with the command shown under
+Admin > Data apps. Wait for the answer.
+
+Then decide:
+
+| HEAD version | working tree | do |
+| ------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| equals target | clean | Nothing to migrate. Say so; run the final gates only if the user asked to verify. |
+| above target | any | **Stop.** There is no downgrade. Either Metabase, the SDK, and the skills are older than the app, or a bump was committed against the wrong instance (`git log -- data_apps/<slug>/data_app.yaml` shows it). Wait for the answer. |
+| below target | clean | Start at _Step 1_. |
+| any | dirty under `data_apps/<slug>` | A previous session was interrupted. Go to _Resuming_ first. |
+
+## Step 1 - Preflight, once
+
+1. Install the SDK that matches the target Metabase release with the app's
+ package manager (`npm install @metabase/embedding-sdk-react@<tag>` or its
+ equivalent); each upgrade guide names the dist-tag it was written against.
+ The lockfile change is committed with the final upgrade.
+2. Confirm the app is template-shaped at its current version: `vite.config.ts`
+ is the one-liner `export default dataAppConfig()` and `src/index.tsx`
+ default-exports a `DataAppFactory`. If not, **Stop**: this is not a version
+ migration but structural drift. Offer to scaffold a fresh app under the same
+ slug (a separate task: use skill discovery for creating a data app) and port
+ `src/`, `queries/`, and `actions/` over, or to proceed at the user's risk.
+ Wait for the answer.
+3. Read every upgrade guide from the current version to the target before editing
+ anything, so a later upgrade cannot surprise you halfway through an earlier one.
+
+## Step 2 - The upgrade loop
+
+For each `N` from the HEAD version up to `target - 1`:
+
+1. Open `references/upgrades/v<N>-to-v<N+1>.md` and run its _Preconditions_.
+2. Apply the guide's _Steps_ in order. Each step is mechanical and ends with a
+ **Done when** command. Run the command first: if it already passes, skip the
+ step; if not, apply the edit and run it again. A step's command is the only
+ proof it happened; never mark a step done by reading.
+3. Apply the _Instance steps_, if any. Their **Done when** is an API response
+ from the connected Metabase, fetched with the credentials from `.env.local`:
+ ```bash
+ ( source "$ROOT/.env.local"; curl -s -H "x-api-key: $DATA_APP_MB_API_KEY" "$DATA_APP_MB_URL/api/apps/<slug>" )
+ ```
+4. Run the guide's _Done-check summary_. Every line must print `ok`.
+5. Only now set `version: N+1` in `data_app.yaml`. This is the one edit to that line.
+6. If `N+1 < target`: from the repo root,
+ `git add data_apps/<slug> && git commit -m "Migrate <slug> data app to data-app version N+1" -- data_apps/<slug>`.
+ The pathspec keeps anything staged outside the app out of the commit.
+ No push, no typecheck, no build. If the user asks why, say the app cannot
+ compile until the last upgrade.
+7. If `N+1 == target`: run _Step 3_ before committing.
+
+Do not batch steps across upgrades. Do not touch `version` before item 5.
+
+## Step 3 - Final gates, at the target version only
+
+1. `npm run typecheck`. Fix failures inside the app's own source. A failure that
+ names an SDK symbol no upgrade guide mentions is a gap in the guides, not a user
+ problem: surface the exact error, say which guide should have covered it, and
+ stop. Otherwise, at most three fix rounds, then stop and ask.
+2. `npm run build`. It runs `sync-resources` and refuses to bundle when
+ definitions and `resources_metadata.json` disagree; follow its message.
+3. `npm run dev`, then take the preview URL from the `Local:` line Vite prints.
+ The template asks for port 5174, but Vite moves to the next free port when
+ that one is taken, so never assume it. Open that URL, then read the
+ diagnostics feed once from the same origin:
+ ```bash
+ curl -s "<preview-url>/__data-app/diagnostics?startEventId=0"
+ ```
+ Expect `clients: 1` and no entry with `"alert": true`. `clients: 0` means no
+ preview tab is open, so an empty feed proves nothing.
+4. `git status` from the repo root must show only: the upgrade edits,
+ `data_app.yaml`, the built bundle, `resources_metadata.json` if resources
+ changed, and the package lockfile if the SDK was re-pinned. Anything else
+ inside the app directory is a user edit; say so before committing.
+5. From the repo root,
+ `git add data_apps/<slug> && git commit -m "Migrate <slug> data app to data-app version M" -- data_apps/<slug>`,
+ push, and tell the user to **Pull changes** under Admin > Data apps.
+6. Prove it. After the pull:
+ ```bash
+ ( source "$ROOT/.env.local"; curl -s -H "x-api-key: $DATA_APP_MB_API_KEY" "$DATA_APP_MB_URL/api/apps/<slug>" )
+ ```
+ must show `"version": M`, `"outdated": false`, and `"sync_error": null`.
+ A response holding only `name` and `display_name` means the key is not an
+ admin's: ask for one, or ask the user to read the admin list, and say the
+ proof is still pending. Report the command and the result. Do not claim the
+ migration is done without it.
+
+## Resuming an interrupted migration
+
+A fresh session has no memory of the previous one and needs none. Read the
+three numbers from _Step 0_ and `git status --porcelain -- data_apps/<slug>`,
+then:
+
+| tree | working-tree version | meaning | do |
+| ----- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| clean | equals HEAD | every finished upgrade is a commit; nothing half done | continue the loop from the HEAD version |
+| dirty | equals HEAD | upgrade `HEAD -> HEAD+1` was in progress and its checks had not all passed | re-run every **Done when** of that upgrade; apply only the steps whose command fails; continue from loop item 4 |
+| dirty | equals HEAD + 1 | all checks passed and the bump was written, but the commit is missing (or the final gates failed after the bump) | re-run that upgrade's _Done-check summary_ (all `ok`, or someone edited after the bump: stop and show `git diff`); if it is the target, run the final gates; commit |
+| any | more than HEAD + 1, or below HEAD | an invariant was broken | **Stop.** Show `git diff -- data_apps/<slug>/data_app.yaml` and ask whether to take that one file back to HEAD and re-derive, or to stash the tree. Wait for the answer. |
+
+Files dirty outside `data_apps/<slug>` are not yours: never `git add` them.
+
+## Reporting
+
+One line per upgrade, in order: `v1 -> v2: done (commit abc1234)` or
+`v2 -> v3: blocked - <the exact Done-when command that fails and its output>`.
+Never soften a failing check. Keep `tsc` output grouped by root cause with a
+few representative diagnostics rather than pasting it whole.
+
+## Never do
+
+- Set or edit `version` before the upgrade's checks pass, or by more than one at a time.
+- Skip an upgrade, or apply two upgrades' steps at once.
+- Run `npm run typecheck` or `npm run build` before the last upgrade, or push before the final gates pass.
+- Hand-edit `savedQuestionSourceId`, `copiedActionId`, `resources_metadata.json`, or `dist/`.
+- Copy a step's outcome from the previous session's chat instead of re-running its **Done when**.
+- Migrate with a checklist of your own when an upgrade guide exists; when one does not exist for an upgrade you need, stop and say so.
+
+## Upgrade guides
+
+Guides live in `references/upgrades/`, one per upgrade, named `v<N>-to-v<N+1>.md`. They
+are written by Metabase when the contract version is bumped, from the template
+in `references/upgrade-guide-template.md`; `references/maintainer-checklist.md`
+describes that process. A missing guide for an upgrade you need is a bug in the
+skill install, not something to improvise around.
diff --git a/skills/metabase-data-app-migrate/references/maintainer-checklist.md b/skills/metabase-data-app-migrate/references/maintainer-checklist.md
new file mode 100644
index 00000000000..2b4427f61e1
--- /dev/null
+++ b/skills/metabase-data-app-migrate/references/maintainer-checklist.md
@@ -0,0 +1,43 @@
+# Maintainer checklist: bumping the data-app contract version
+
+For Metabase engineers, not for agents migrating an app. The version is bumped
+only for a change an app author must act on. Decide the category first:
+
+| Change | Bump? | Proven by | What the upgrade guide contains |
+| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `@metabase/embedding-sdk-react/data-app` API: components, hooks, types, the bundle factory, `providerProps` | yes, after one deprecation release | `npm run typecheck` | the symbol table from the `.d.ts` diff, with replacements |
+| `data_app.yaml` fields, `queries/` and `actions/` conventions, generated-id keys, `resources_metadata.json` format | yes | `npm run build` (`sync-resources`) | mechanical steps; `sync-resources` upgrades the state it owns |
+| What an app may declare or run under the permission model | yes | the instance API, read by the agent with the app's API key | instance steps whose _Done when_ is an API response |
+| Instance-only changes: the app group's grants, collection layout, provisioning | **no** | nothing app-side | none; ship a backend migration and make provisioning converge on the next pull |
+
+Deprecation policy for `/data-app` exports: a rename keeps the old name for one
+release as a `@deprecated` alias, wired at the fallback point in
+`enterprise/frontend/src/metabase-enterprise/data_apps/sandbox/sandbox.ts`
+(the `dataAppExports` spread), so old bundles keep running. The release that
+deletes the alias bumps the contract version and ships the upgrade.
+
+## In the bump PR
+
+1. `enterprise/backend/src/metabase_enterprise/data_apps/config.clj`:
+ `supported-app-version` to `N+1`. `initial-app-version` stays 1.
+2. `skills/metabase-data-app-setup/template/data_app.yaml`: `version: N+1`.
+ Update the template's source if the contract change touches it.
+3. Every e2e fixture manifest that declares a version
+ (`e2e/support/assets/data-apps/*/data_app.yaml`,
+ `e2e/support/assets/example_synced_data_apps/data_apps/*/data_app.yaml`,
+ `e2e/embedding-sdk-host-apps/*/data_app.yaml`): `version: N+1`.
+4. `skills/metabase-data-app-migrate/references/upgrades/v<N>-to-v<N+1>.md` from
+ `upgrade-guide-template.md`, every section filled. Build the symbol table from
+ `git diff <previous-release-tag> -- resources/embedding-sdk/dist/data-app.d.ts`
+ after regenerating the declarations (`bun run embedding-sdk:dts:generate`).
+5. Verify the guide by hand: take a fresh copy of the _previous_ release's
+ template, apply the guide, confirm every _Done when_ prints `ok`, then
+ `npm run typecheck && npm run build` pass at `N+1`. Confirm every _Done when_
+ also passes unchanged on the new template.
+6. Remove any `@deprecated` alias kept for the previous release at the
+ `sandbox.ts` fallback point; that removal is the breaking change.
+7. `enterprise/frontend/src/embedding-sdk-package/CHANGELOG.md`: a "Data apps
+ contract v<N+1>" entry linking the upgrade guide.
+8. Run `./bin/test-agent :only '[metabase-enterprise.data-apps.config-test]'`.
+ Two tests fail until steps 1, 2, and 4 agree: the template must declare the
+ supported version, and the upgrade guides must cover every version from 1 up to it.
diff --git a/skills/metabase-data-app-migrate/references/upgrade-guide-template.md b/skills/metabase-data-app-migrate/references/upgrade-guide-template.md
new file mode 100644
index 00000000000..f0735c940c1
--- /dev/null
+++ b/skills/metabase-data-app-migrate/references/upgrade-guide-template.md
@@ -0,0 +1,110 @@
+# Upgrade guide template
+
+Copy this file to `upgrades/v<N>-to-v<N+1>.md` and fill every section. Delete the
+guidance in angle brackets. Rules the template encodes:
+
+- Every step is mechanical and idempotent: applying it twice is a no-op, and its
+ **Done when** command decides whether it is still needed.
+- A **Done when** for a code step inspects the app's own tree (grep, file
+ presence), never compiler output: the app cannot compile until the last upgrade.
+ A **Done when** for an instance step is an API response.
+- The symbol table is complete, types included. Derive it from the diff of
+ `resources/embedding-sdk/dist/data-app.d.ts` (and `index.d.ts` for main-entry
+ components apps use) between the two releases.
+- Every command in the guide must pass unchanged on a fresh copy of the new
+ template, and the whole guide must take a fresh copy of the previous template
+ to a passing `npm run typecheck && npm run build`.
+
+````markdown
+# Data app contract v<N> -> v<N+1>
+
+Metabase release: <x.YY> SDK tag: <YY-alpha | YY-stable> PR: <#>
+
+## Why this is a breaking change
+
+<One paragraph: what an app built for v<N> does on a v<N+1> Metabase without
+these edits, e.g. "the bundle refuses to load because `useFoo` no longer exists
+on the endowed `/data-app` export".>
+
+## Preconditions
+
+Run from the app directory. Every command must print `ok`.
+
+```bash
+grep -q 'export default dataAppConfig()' vite.config.ts && echo ok
+grep -q 'DataAppFactory' src/index.tsx && echo ok
+<upgrade-specific precondition, if any>
+```
+
+If one fails, stop: the app is not template-shaped at v<N>. See SKILL.md, Step 1.
+
+## Removed and renamed symbols
+
+| Symbol | Entry point | Change | Replacement |
+| ---------- | ---------------------------------------- | ------------ | --------------------- |
+| `oldName` | `@metabase/embedding-sdk-react/data-app` | renamed | `newName` |
+| `gone` | `@metabase/embedding-sdk-react/data-app` | removed | <what to use instead> |
+| `OldProps` | `@metabase/embedding-sdk-react/data-app` | type removed | `NewProps` |
+
+Every row is a `tsc` error at v<N+1>. List types as well as values.
+
+## Other contract changes
+
+<Manifest fields, `queries/` and `actions/` layout, generated-id keys, factory
+shape, `providerProps`, sandbox rules, what an app may declare, or "none".>
+
+## Steps
+
+### Step 1 - <imperative title>
+
+Files: `src/**/*.tsx`
+
+Before:
+
+```tsx
+import { oldName } from "@metabase/embedding-sdk-react/data-app";
+```
+
+After:
+
+```tsx
+import { newName } from "@metabase/embedding-sdk-react/data-app";
+```
+
+Notes: <edge cases; what NOT to touch>
+
+Done when:
+
+```bash
+! grep -rqE '\boldName\b' src queries actions && echo ok
+```
+
+### Step 2 - <imperative title>
+
+<same shape>
+
+## Instance steps
+
+<Steps whose effect lives in Metabase rather than in the repo, or "none". Each
+ends with a **Done when** that reads the API:>
+
+Done when:
+
+```bash
+( source "$ROOT/.env.local"; curl -s -H "x-api-key: $DATA_APP_MB_API_KEY" "$DATA_APP_MB_URL/api/apps/<slug>" ) | grep -q '"sync_error":null' && echo ok
+```
+
+## Done-check summary
+
+All of this upgrade's **Done when** commands in one block. Every line must print `ok`.
+
+```bash
+( ! grep -rqE '\boldName\b' src queries actions && echo ok )
+( <step 2 command> && echo ok )
+```
+
+## After this upgrade
+
+<Follow-ups with their exact commands, e.g. "regenerate `src/metabase.data.ts`:
+<curl command>", or "nothing". If this is not the final upgrade, nothing is built.>
+````
diff --git a/skills/metabase-data-app-migrate/references/upgrades/README.md b/skills/metabase-data-app-migrate/references/upgrades/README.md
new file mode 100644
index 00000000000..12149d6872c
--- /dev/null
+++ b/skills/metabase-data-app-migrate/references/upgrades/README.md
@@ -0,0 +1,9 @@
+# Upgrade guides
+
+One file per contract-version upgrade, named `v<N>-to-v<N+1>.md`, written from
+`../upgrade-guide-template.md` when Metabase bumps the data-app contract version.
+
+The highest `<N+1>` here is the version this skill migrates to. No files means
+the current version is 1 and there is nothing to migrate yet. Upgrades are never
+skipped: an app at version 1 migrating to version 4 applies `v1-to-v2.md`,
+`v2-to-v3.md`, then `v3-to-v4.md`, in that order, with one commit each.
diff --git a/skills/metabase-data-app-setup/SKILL.md b/skills/metabase-data-app-setup/SKILL.md
index 1603ec2c781..fc19a98cc78 100644
--- a/skills/metabase-data-app-setup/SKILL.md
+++ b/skills/metabase-data-app-setup/SKILL.md
@@ -50,10 +50,15 @@ If `<repo>/data_apps/<slug>/` already holds a project, verify it matches the cur
2. `src/index.tsx` default-exports a `DataAppFactory` (type from
`@metabase/embedding-sdk-react/data-app`) returning `{ component, providerProps? }`
(no args).
+3. `data_app.yaml` declares the same `version:` as this skill's
+ `template/data_app.yaml` (a manifest without the line is version 1). A lower
+ version is not drift but an outdated app: **Stop.** Migrating it is a
+ separate task; use the agent's normal skill-discovery flow for migrating an
+ outdated data app before extending it.
**All checks pass** → template-shaped. Ask: "Extend this app, or scaffold a new one under a different slug?" If extend → skip the copy step, edit `src/`. If new → pick a different slug and restart at Step 2.
-**Any check fails** → not template-shaped (older scaffold or drift). **Stop.** Tell the user the structure differs from the current template, extending it risks breaking the bundle contract, and ask whether to (1) migrate it, (2) scaffold fresh under a new slug and port the code over, or (3) proceed anyway at their risk. Wait for the answer.
+**Any check fails** → not template-shaped (older scaffold or drift). **Stop.** Tell the user the structure differs from the current template, extending it risks breaking the bundle contract, and ask whether to (1) migrate it (a separate task; use skill discovery for migrating an outdated data app), (2) scaffold fresh under a new slug and port the code over, or (3) proceed anyway at their risk. Wait for the answer.
Never overwrite existing files without explicit confirmation.
@@ -157,8 +162,8 @@ Once the template is in `<repo>/data_apps/<slug>/` (run everything below from th
change to the contract. An app on an older version is marked *Outdated* in
the admin list, hidden from every other user, and refuses to open until it
is migrated to the current contract, its `version` raised to match, rebuilt,
- and synced. Migrating an app from one version to the next is a separate,
- instructed procedure; never do it ad hoc.
+ and synced. That migration is a separate, instructed procedure, one version
+ at a time; reach it through skill discovery and never do it ad hoc.
**`allowed_hosts`** — only needed if the app calls an **external** API directly
with `fetch`/`XHR`. The sandbox blocks all network egress by default; listing an
diff --git a/skills/metabase-data-app-setup/template/README.md b/skills/metabase-data-app-setup/template/README.md
index 7a0befc9af2..d07d1c385ec 100644
--- a/skills/metabase-data-app-setup/template/README.md
+++ b/skills/metabase-data-app-setup/template/README.md
@@ -34,6 +34,14 @@ Commit `dist/index.js` (the `path` declared in `data_app.yaml`) along with your
source. The app appears at `/apps/<slug>` after Metabase's next remote-sync
import (manual "Pull changes", auto-import, or startup).
+## Upgrading
+
+`data_app.yaml` declares the data-app contract version this app targets. When a
+Metabase release bumps that version, the app shows as _Outdated_ in the admin UI
+until it is migrated. Migration is its own instructed procedure, installed for
+your coding agent by the same command as the other data-app skills; do not edit
+`version` by hand.
+
## What's in the box
```