The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
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.cljindex 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.tsxindex 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.tsxindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex 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 cur2. `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 thchange to the contract. An app on an older version is marked *Outdated* inthe admin list, hidden from every other user, and refuses to open until itis 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 directlywith `fetch`/`XHR`. The sandbox blocks all network egress by default; listing andiff --git a/skills/metabase-data-app-setup/template/README.md b/skills/metabase-data-app-setup/template/README.mdindex 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 yoursource. The app appears at `/apps/<slug>` after Metabase's next remote-syncimport (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```