@metabase/cli 0.5.3 → 0.5.5

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 | data-app | 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,10 +153,10 @@ 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`).
+- **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`). On a remote-sync instance, `mb git-sync add-collection <library-id>` (the root) makes exports carry published tables' metadata (see `git-sync`).
 <!-- /requires -->
 - **query / uuid.** `mb query` runs MBQL (`--dry-run` → run; `mbql`). `mb uuid --count <n>` mints an aggregation's `lib/uuid` (`mbql`) and document node `_id`s (`document`).
 <!-- requires: library, tableListPublishedFilter -->
@@ -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 (`mb skills get <name>`) **proactively** — don't wing it 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).
@@ -184,6 +185,9 @@ This file is enough for any single-command task. For anything deeper, load the r
   <!-- /requires -->
   <!-- requires: remoteSync -->
 - **`git-sync`** — round-tripping content to/from a git remote.
+  <!-- /requires -->
+  <!-- requires: dataApps -->
+- **`data-app`** — data apps: create, preview, publish (start here).
 <!-- /requires -->
 - **`data-workflow`** — the guided, end-to-end data workflow: investigate raw data, build clean analysis-ready tables, define reusable segments/measures/metrics, answer questions, build dashboards. **Start here when the user states a goal rather than a single verb** — "make sense of my data", "build a data model", "be my data analyst". It detects where the data is and routes to the right stage.
 

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

@@ -1,6 +1,6 @@
 ---
 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`.
+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 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]
 ---
@@ -17,11 +17,11 @@ The work, in order:
 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.
+For every later change: regenerate `src/metabase.ts` if the app's collection changed, then build and set the bundle; in a synced repository, then export and commit the source as in _Move to another instance_. Metabase receives only the built bundle; the source stays in the project directory, which is the app's folder in the synced git repository when there is one (_Scaffold and install_).
 
 ## 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`).
+- Use an **admin** profile — only admins create apps and write the app's collection. `mb auth status --profile <name> --json | jq .user.isAdmin` prints `true` for one, and every command below takes that `--profile`; 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.
 
@@ -31,18 +31,18 @@ For every later change: regenerate `src/metabase.ts` if the app's collection cha
 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.
+`name` is the slug; `display_name` and `description` are optional. The app starts enabled, with an empty bundle, open to admins until a group is assigned. 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
+mb data-app scaffold <repo>/data_apps/sales-overview && cd <repo>/data_apps/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:
+`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. When the instance syncs with a git repository (`mb git-sync status`), the directory is `data_apps/<slug>/` in a local clone of that repository (ask the user for its path, or clone the remote), where an export writes the app's `data_app.yaml` and bundle: an export leaves the source alone and an import ignores it, so the repository keeps the source with the app. `scaffold` needs an empty directory, so scaffold before the app's first export; for an app already in the repository, scaffold into a new directory and copy its files, dotfiles included (`cp -R <dir>/. data_apps/<slug>/`), in beside `data_app.yaml` and `dist/`; check `.gitignore` is there before `npm install`. Without a repository, use any new directory, and once remote sync is set up, move the project (without `node_modules/`, `dist/`, `.env.local` and a hand-written `data_app.yaml`) into `data_apps/<slug>/` before committing its source. 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 @metabase/embedding-sdk-react@<major>-beta   # <major>: 66 for a version tag v1.66.x (`mb auth status --profile <name> --json | jq -r .version.tag`)
 npm install && npm run typecheck && npm run build
 ```
 
@@ -58,12 +58,12 @@ The template is the bundle contract. Don't edit `package.json` by hand, and neve
 
 ```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)
+  URL=$(mb auth status --profile <name> --json | jq -r .url)
+  KEY=$(mb api-key create --profile <name> --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.
+Group `2` is Administrators. Never print `.env.local`. Delete the key at handoff (`mb api-key list --profile <name>`, then `mb api-key delete <id> --yes --profile <name>`); the next session writes a new one. Metabase allows any localhost origin unless `MB_DISABLE_CORS_ON_LOCALHOST` is set, so a CORS error from the preview means it is: ask the user to unset it on this instance. Otherwise check `DATA_APP_MB_URL`.
 
 ### The diagnostics feed
 
@@ -96,7 +96,7 @@ curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"
 - `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.
+- 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`, and in a synced repository you set `allowed_hosts` with `mb data-app update`, export, and pull the export branch (_Move to another instance_) instead of editing `data_app.yaml`. A `frame-src` or `form-action` block can't be lifted in the preview (`data-app-ui`). The feed keeps the last 200 entries; `curl -X DELETE …/__data-app/diagnostics` clears it.
 
 | `kind`                             | Fix                                                                                                                 |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
@@ -110,12 +110,11 @@ curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"
 ```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>`.
+`set-bundle` uploads `dist/index.js` (`--bundle` for another path) and replaces the app's bundle, live at once. A new app is on from the start; `mb data-app set-enabled <slug> false` turns it off, which only the user decides. An app turned off opens only in Data Studio → Data apps → the app → Overview; `/apps/<slug>` says "not found", for admins too. 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.
+A viewer needs one of their groups assigned to the app (otherwise "You don't have access"), which only the user can do (Data Studio → Data apps → the app → Permissions). A group reaches the app's collection and nothing more, so a viewer also needs data access to the tables its questions read.
 
 ## Pitfalls
 
@@ -133,6 +132,6 @@ Admins open every app, enabled or not. Anyone else needs the app enabled (otherw
 ## 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.
+- **Outdated:** an app Data Studio lists as _Outdated_ targets an older data-app contract: it won't open for anyone, and only admins see it, 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` works there. The first import there creates the app on, like `create`, open to admins until the user assigns groups; later imports keep its on/off state. The import doesn't check that the questions' tables are published on that instance, so the Library content they read goes in the same export: flag the Library root once (`mb git-sync add-collection <library-id>`, `git-sync`), or its metrics, measures and segments stay out of the repository; a data action needs its database's toggle on there too. Once the app is done, commit its source in `data_apps/<slug>/` on the branch you exported to, after the export. Pull the export branch: `git restore` a modified `dist/index.js`, then `git fetch`, `git switch <branch>`, `git pull --ff-only`. Then `git add data_apps/<slug>`, commit and push, and `mb git-sync import` whatever a cached `has-remote-changes` says, or the next export ends in `conflict`. The export writes `data_app.yaml` and `dist/index.js`, the bundle you uploaded; never edit or commit those two yourself, and when a fresh build changes `dist/index.js`, set the bundle and export again instead. The template's `.gitignore` keeps `node_modules/` and `.env.local` out. On a read-only synced instance only `set-enabled` works: creating, bundling, updating and deleting an app answer 403, and so does editing its collection; 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: in a synced repository, the next export removes the app's `data_app.yaml`, bundle and collection files; after that export, switch and pull the same way, delete the source in `data_apps/<slug>/` in a commit of your own, push, and import.

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

@@ -7,7 +7,7 @@ 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`);
+`<major>` is 66 for a version tag v1.66.x (`mb auth status --profile <name> --json | jq -r .version.tag`);
 `package.json` asks for any version, which would install `latest`.
 
 ```bash

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

@@ -13,6 +13,8 @@ An **action** is a saved, parameterized SQL write — `INSERT`, `UPDATE` or `DEL
 2. Regenerate `src/metabase.ts` (`data-app-data`).
 3. Pass `actions.<name>` from it to `useAction`.
 
+An action in the app's collection can't be archived: to drop one, move it to a data actions collection (`mb data-action update <id> --body '{"collection_id":<id>}'`), then archive it.
+
 Each action there lists its parameters: the parameter slug (the key `execute` takes), `displayName` (a label, never a key), `jsType` (`string`, `number`, `Date`, `boolean` or `unknown`) and `required`. Never fake a call to an action `src/metabase.ts` doesn't list.
 
 ## The hook
@@ -83,6 +85,7 @@ export function NoteForm({ orderId, onSaved }: { orderId: number; onSaved: () =>
 After a write succeeds, refetch every query on screen it could have changed: `await Promise.all([orders.refetch(), totals.refetch()])`, the `refetch` that `useMetabaseQuery` returns.
 
 - Those queries live in a component above the trigger, which passes the refresh down; a query in the trigger's own component or below it can't be wired to it.
+- A `StaticQuestion` panel has no `refetch`: give it a `key` the parent bumps after the write, which remounts it and runs the question again.
 - Await the refresh before clearing the form or closing the modal, so stale rows never flash.
 - Never prepend `result` to a local list instead: ids, timestamps and computed columns come from the server.
 

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

@@ -15,11 +15,11 @@ A data app runs only the questions and actions in **the app's collection** (`dat
 
 ## Sources: the semantic layer only
 
-An app reads only what the user curated in the Library. These are hard rules:
+An app reads only what the user curated in the Library. Metabase refuses a question in the app's collection that breaks these rules:
 
-- **Tables published to the Library**, and nothing else: `mb table list --published-only --json`. That covers the question's source table, every join, and every table reached through a foreign key column.
-- **Metrics in the Library's Metrics collection** (its id is in `mb library get`; list it with `mb collection items <id> --json`), and the segments and measures of published tables (`mb segment list`, `mb measure list`). Prefer one that matches the concept over rebuilding it with filters and thresholds of your own.
-- **Other questions in the app's collection**, as a source. Never a question, model or metric from anywhere else.
+- **Tables published to the Library**, and nothing else: `mb table list --published-only --json`. That covers the question's source table, every join, every table reached through a foreign key column, the tables behind its segments and measures, and the tables whose columns Metabase shows in place of a foreign key.
+- **Metrics in the Library's Metrics collection**, as aggregations (its id is in `mb library get`; list it with `mb collection items <id> --json`), and the segments and measures of published tables (`mb segment list`, `mb measure list`). Prefer one that matches the concept over rebuilding it with filters and thresholds of your own.
+- **No other question as a source** — not a question in the app's collection, a model or a metric. Every question starts from a published table.
 - **MBQL only**, never native SQL.
 
 When the app needs a table or metric the Library lacks, stop: name what's missing and ask the user to publish the table or move the metric into the Library. Don't publish it yourself unless the user says to, and never work around the gap with an unpublished table, a copy of the data, or SQL.
@@ -44,7 +44,7 @@ mb card query <id> --json --max-bytes 0 | jq '{row_count, first: .data.rows[0]}'
 Plan the questions from what the app shows and picks from — each chart, KPI, table and filter option list needs one, and several panels may share one. Each takes one of two shapes:
 
 - **Aggregated**, when the breakdown is fixed: revenue by month, top products. Runtime clauses can then name only the columns it returns, its breakouts and aggregations.
-- **Rows**, when a runtime filter targets a column an aggregation would drop — revenue by month, filtered by product category. The question returns the raw columns (`CREATED_AT`, `TOTAL`, `CATEGORY`), and the hook filters and aggregates them at runtime (_Runtime clauses_).
+- **Rows**, when a runtime filter targets a column an aggregation would drop — revenue by month, filtered by product category. The question returns the raw columns (`CREATED_AT`, `TOTAL`, `CATEGORY`), and the hook filters and aggregates them at runtime (_Runtime clauses_). When a Library metric or measure defines the number, never rebuild it from rows: filter an aggregated question instead (_Runtime clauses_).
 
 Also:
 
@@ -150,7 +150,7 @@ const { query } = useMetabaseQueryObject(queries.orderRows, {
 - `filter(...)` takes one value: `filter(col, "=", [a, b])` compiles but is not an IN filter, and several filters AND together. So a filter picks one value or All; for a multi-select, ask the user whether a single choice will do.
 - Text operators are case-sensitive, with no option to change it: say so in the search box's placeholder.
 - `time-interval` (`[-30, "day"]`, `[0, "year"]` for this year) is relative to when the query runs: a fixed window belongs in the question, not the hook.
-- On a rows question, aggregate with any of `aggregations.count`, `sum`, `avg`, `median`, `min`, `max`, `distinct`, naming each result (`{ name: "revenue" }`) to order or read it by — two unnamed results of one operator collide, and generated names such as `sum_2` aren't stable. On an aggregated question, re-aggregate only sums and counts, which add up.
+- On a rows question, aggregate with any of `aggregations.count`, `sum`, `avg`, `median`, `min`, `max`, `distinct`, naming each result (`{ name: "revenue" }`) to order or read it by — two unnamed results of one operator collide, and generated names such as `sum_2` aren't stable. Never aggregate an aggregated question at runtime: a sum over its rows is wrong for distinct counts, averages, ratios and levels such as MRR. A runtime filter only picks its rows. So a date filter on it offers presets of whole, complete buckets at the question's own grain (Last month, Last 12 months on a month question), each range from the first bucket's start to the last bucket's start, and no Custom range; a KPI shows one bucket, as `scalar` (a `smartscalar` filtered to one bucket loses its comparison), with no All time. A filter on a column needs a question broken out by that column too; its All is no clause when the panel shows that column (a series per value), and otherwise a second question without that breakout, both hooks called and switched with `enabled`. When a request needs more, say so.
 - A sort the user picks: map each choice to a column explicitly (`{ revenue: "revenue", orders: "order_count" }`) rather than passing the user's value through.
 - `enabled: false` holds the query back, for example until the user picks an item.
 - Write the arrays inline (spreads are fine): the hooks compare by content, so a new array per render doesn't refetch. A clauses object built outside the call needs `as const`, or `aggregations` loses the tuple type `breakouts` need; a shared `ReturnType<typeof filter>[]` built with `push` breaks the operator types the same way.

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

@@ -19,12 +19,13 @@ Before any control, write one row per filter: the question that gives its option
 | Plan      | orders broken out by plan  | plan text    | orders                 | revenue, stock |
 
 - A filter in the page's global bar changes every panel that can take it. One that can't reach a panel is scoped to its section, visibly, or left out. A KPI and its detail table about the same thing take the same filters, unless the UI says why not.
+- A KPI on an aggregated question shows one complete bucket (`data-app-data`, _Runtime clauses_): it gets its own control of one-bucket presets starting at the last complete bucket, never All time, rather than a shared bar's ranges.
 - One date control per scope. Never a global date range beside a page-specific date where one of the two does nothing; a page whose cards use another date column gets one control for that column.
 - Build each panel's clauses from its own question's columns, inline at its hook call. Never reuse an array built for another question.
 
 ## Values and options
 
-- Every filter starts at **All**. Keep it as `"all"` in state and send it as no clause (`[]`); treat `""`, `null` and `undefined` the same way. In a Yes/No/All filter, Yes and No each filter (`true`, `false`), and only All sends nothing.
+- Every filter starts at **All**, except a KPI's own date control (above). Keep it as `"all"` in state and send it as no clause (`[]`), except on an aggregated question whose panel doesn't show the filtered column, where All is its own question (`data-app-data`, _Runtime clauses_); treat `""`, `null` and `undefined` the same way. In a Yes/No/All filter, Yes and No each filter (`true`, `false`), and only All sends nothing.
 - Options come at runtime from their own question in the app's collection, broken out on the filtered column — never hardcoded unless the user gave a closed list. Dedupe them from its rows, and keep the label apart from the value.
 - Filter by a stable raw value (an id) and show its label; never filter by a display label when an id exists, and never feed free text into an exact-id filter.
 - All stays selectable while options load, come back empty or fail; don't disable the control. When fresh options no longer hold the selected value, reset to All:
@@ -48,7 +49,7 @@ Any list whose options come from a question — an id shown as a name, a categor
 
 ## Date ranges
 
-A preset bar lists the durations, then All time, then Custom last — leave Custom out only if the user asked for fixed presets. Every option ends in the same `[start, end]` range (All time is `[null, null]`), so one `between` filter serves them all. Custom is `DateRangePopover` around your own trigger, or `DateRangeCalendar` inline, both from `@metabase/embedding-sdk-react/data-app`. No date-picker library and no `<input type="date">` for a range.
+A preset bar lists the durations, then All time, then Custom last — leave Custom out only if the user asked for fixed presets, or the bar filters an aggregated question, which offers only whole, complete buckets and no All time on a KPI (`data-app-data`, _Runtime clauses_). Every option ends in the same `[start, end]` range (All time is `[null, null]`), so one `between` filter serves them all. Custom is `DateRangePopover` around your own trigger, or `DateRangeCalendar` inline, both from `@metabase/embedding-sdk-react/data-app`. No date-picker library and no `<input type="date">` for a range.
 
 ```tsx
 import { DateRangePopover, filter, useDateFormatter } from "@metabase/embedding-sdk-react/data-app";
@@ -68,7 +69,7 @@ const [start, end] = range;
 - Label it with `formatDateRange(range)` (or `formatDate` for one end), which formats in the instance's locale; both take a dayjs `format`, and `formatDateRange` a `separator`. It returns `""` until the SDK loads. Never `new Date("YYYY-MM-DD")`: a date-only string parses as UTC and shows the previous day west of Greenwich.
 - The popover closes once both ends are picked (`closeOnSelect`); `opened` and `onOpenedChange` control it yourself. Also `defaultValue`, `minDate` and `maxDate` (`YYYY-MM-DD`), `numberOfColumns` (default 2) and `position` (default `bottom-start`). `DateRangeCalendar` takes the same value props plus `className` and `style`.
 
-A preset's range, from local dates — never `toISOString()`, which shifts the day:
+A preset's range, from local dates — never `toISOString()`, which shifts the day. `lastMonths` is a rolling window, for a rows question; on a month question, `lastCompleteMonths` gives bucket starts:
 
 ```ts
 const ymd = (d: Date) =>
@@ -78,10 +79,17 @@ const lastMonths = (n: number): [string, string] => {
   const start = new Date(end.getFullYear(), end.getMonth() - n, end.getDate());
   return [ymd(start), ymd(end)];
 };
+const lastCompleteMonths = (n: number): [string, string] => {
+  const now = new Date();
+  return [
+    ymd(new Date(now.getFullYear(), now.getMonth() - n, 1)),
+    ymd(new Date(now.getFullYear(), now.getMonth() - 1, 1)),
+  ];
+};
 ```
 
 **A single date or a date-time** is the one case for a library: `npm install react-datepicker`, import `react-datepicker/dist/react-datepicker.css`, type the callback (`(date: Date | null) => …`), and convert with `ymd` above. Pass `null`, never `new Date("")`, for an empty value.
 
 ## Check
 
-For every visible filter: All runs the unfiltered question; its options come from a question; each option changes every panel the contract says it reaches, and no other; a preset bar ends with Custom; and no scope has two date controls. Search the filter controls for `<select` and `type="date"` — an action form keeps its date inputs. Then build and publish (`data-app`, _Build and publish_).
+For every visible filter except a KPI's own date control: All runs the unfiltered question, or its All question; its options come from a question; each option changes every panel the contract says it reaches, and no other; a preset bar ends with Custom unless it filters an aggregated question; and no scope has two date controls. Search the filter controls for `<select` and `type="date"` — an action form keeps its date inputs. Then build and publish (`data-app`, _Build and publish_).

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

@@ -35,7 +35,7 @@ Everything here runs inside the sandbox, the same in the dev preview as in Metab
 | `navigator.geolocation` and other device APIs                                                              | Nothing.                                                                                  |
 | Key, input, composition and clipboard listeners (`keydown`, `paste`, `input`, …) on `window` or `document` | A React handler (`onKeyDown`, `onPaste`, …) on your own element.                          |
 
-**External APIs.** A raw `fetch` reaches only the origins in the app's `allowed_hosts`, exact or with a `*.` subdomain wildcard: `mb data-app update <slug> --body '{"allowed_hosts":["https://api.example.com"]}'`, plus an `allowed_hosts:` list in `data_app.yaml` beside `package.json` for the preview, then restart `npm run dev`. Never list the Metabase URL. In Metabase the same list governs `<iframe src>` and native `<form action>` submits, and the target must allow framing; the preview blocks both. Use `<form onSubmit>` with `preventDefault`: a native submit navigates the app away.
+**External APIs.** A raw `fetch` reaches only the origins in the app's `allowed_hosts`, exact or with a `*.` subdomain wildcard: `mb data-app update <slug> --body '{"allowed_hosts":["https://api.example.com"]}'`. The preview reads the `allowed_hosts:` list in `data_app.yaml` beside `package.json`: in a synced repository that file is the app's exported manifest, so export again and pull the export branch (`data-app`, _Move to another instance_) to refresh it rather than writing it; without one, write the list there yourself. Then restart `npm run dev`. Never list the Metabase URL. In Metabase the same list governs `<iframe src>` and native `<form action>` submits, and the target must allow framing; the preview blocks both. Use `<form onSubmit>` with `preventDefault`: a native submit navigates the app away.
 
 ## Layout
 
@@ -69,12 +69,12 @@ export function AppError({ message }: SdkErrorComponentProps) {
 
 ## SDK components
 
-| Import                                                                           | For                                                                   |
-| -------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `StaticQuestion`                                                                 | A chart, KPI or table without drill-through — the default.            |
-| `InteractiveQuestion`                                                            | One meant to be explored: drill-through, chart switching, the editor. |
-| `StaticDashboard`, `InteractiveDashboard`, `EditableDashboard`                   | A dashboard.                                                          |
-| `CreateQuestion`, `MetabotQuestion`, `CollectionBrowser`, `CreateDashboardModal` | Authoring flows, rarely in an app.                                    |
+| Import                | For                                                                                     |
+| --------------------- | --------------------------------------------------------------------------------------- |
+| `StaticQuestion`      | A chart, KPI or table without drill-through — the default.                              |
+| `InteractiveQuestion` | One meant to be explored: drill-through, chart switching; pass `isSaveEnabled={false}`. |
+
+Both take a question in the app's collection. Dashboards and the authoring components (`CreateQuestion`, `CreateDashboardModal`, saving from the editor) don't work in an app: its collection can't hold a dashboard, and an app can't save content.
 
 ## A Metabase chart or your own
 
@@ -82,13 +82,13 @@ Ask "can Metabase draw this at all?", never "which looks closer to the design?"
 
 - **Yes** — bar, line, area, combo, row, pie, scalar, smartscalar, gauge, progress, funnel, scatter, waterfall, boxplot, sankey, pivot, map, tables: render it with `useMetabaseQueryObject` and `StaticQuestion` (`data-app-data`). It keeps the instance's formatting, tooltips, theming and drill-through. Styling is never a reason to draw it yourself.
 - **No**, or the user asked for a custom one — scorecards, timelines, calendar grids, one visual from several queries: draw it from `useMetabaseQuery` rows, with SVG or a chart library the app already has.
-- A KPI is `scalar`, `smartscalar`, `gauge` or `progress`; put what Metabase doesn't draw (a caption, stars) beside it.
+- A KPI is `scalar`, `smartscalar`, `gauge` or `progress` — on a question filtered at runtime to one bucket, `scalar` (a `smartscalar` loses its comparison); put what Metabase doesn't draw (a caption, stars) beside it.
 - `InteractiveQuestion`: pass `isSaveEnabled={false}`, and `title={false}` in a panel with its own heading. Children replace its layout: `<InteractiveQuestion card={card}><InteractiveQuestion.QuestionVisualization height={360} /></InteractiveQuestion>` is the chart alone.
 
-**Visualization settings.** Add `visualizationSettings` only for a change the user asked for. Their keys are a question's `visualization_settings` keys — the `visualization` skill lists them — and the installed types decide what's legal: `rg -n "<key>|declare type .*VisualizationSettings" node_modules/@metabase/embedding-sdk-react/dist/index.d.ts`, never the whole file, never from memory. Keep them few: keys such as `graph.dimensions`, `pie.metric` and `column_settings` name result columns and break when the question changes.
+**Visualization settings.** Add `visualizationSettings` only for a change the user asked for, or `scalar.field` on a KPI whose first column isn't the number. Their keys are a question's `visualization_settings` keys — the `visualization` skill lists them — and the installed types decide what's legal: `rg -n "<key>|declare type .*VisualizationSettings" node_modules/@metabase/embedding-sdk-react/dist/index.d.ts`, never the whole file, never from memory. Keep them few: keys such as `graph.dimensions`, `pie.metric` and `column_settings` name result columns and break when the question changes.
 
 - A `table` with two breakouts and one aggregation renders as a pivot when a breakout has at most 16 values; `{ "table.pivot": false }` keeps one row per group.
-- A scalar shows the first column: with a key column first, point it at the number with `{ "scalar.field": "avg_rating" }`.
+- A scalar shows the first column: with a key or breakout column first (a date on a month question), point it at the number with `{ "scalar.field": "avg_rating" }`.
 - A header: `column_settings: { '["name","approvers"]': { column_title: "Approvers" } }`.
 
 ## Pages
@@ -117,4 +117,4 @@ Metabase mirrors each route to `/apps/<slug>/<path>`, and a reload there opens t
 
 ## Before handoff
 
-`npm run dev` only transpiles: run `npm run typecheck` after every round of edits and fix what it reports, and report the result, errors grouped by cause. Search the changed files and fix what turns up: `card={{` (every `card` comes from `useMemo`), `row[0]` and `as unknown as` (rows are keyed by column name), `<select` for a list from a question (`data-app-filters`), `type="date"` and `new Date(` in a date filter, `* 100` and `%`. Read the diagnostics feed with every panel mounted, then build and publish (`data-app`, _Build and publish_).
+`npm run dev` only transpiles: run `npm run typecheck` after every round of edits and fix what it reports, and report the result, errors grouped by cause. Search the changed files and fix what turns up: `card={{` (every `card` comes from `useMemo`), `row[0]` and `as unknown as` (rows are keyed by column name), `<select` for a list from a question (`data-app-filters`), `type="date"` and `new Date("` (a date string parsed as UTC) in a date filter, `* 100` and `%`. Read the diagnostics feed with every panel mounted, then build and publish (`data-app`, _Build and publish_).

package/skill-data/data-workflow/references/reusable-definitions.md

@@ -49,7 +49,7 @@ Two things never bend in any mode: when genuinely unsure, **ask** (the Shared Co
   - "Let me filter to just the active ones" → a **segment** (saved filter).
   - "Let me add up revenue the same way everywhere, on this table" → a **measure** on the table.
   - "Revenue is an _official company number_ people pull onto dashboards" → a **metric** in a collection, with a default month-by-month view so it charts cleanly. Lean: make it a metric when it's a headline figure the org reuses across many questions/dashboards; keep it a measure when it's a table-local convenience.
-- **Where the metric lives.** Metrics sit in a collection (folder). Lean: put the org's blessed ones in the shared **Library** so they surface prominently; keep experimental ones in a working collection until trusted.
+- **Where the metric lives.** Metrics sit in a collection (folder). Lean: put the org's blessed ones in the Library's **Metrics** collection so they surface prominently; keep experimental ones in a working collection until trusted.
 <!-- requires: library -->
 - **Publish the official tables to the Library.** The clean, analysis-ready tables your definitions sit on are the org's official starting points — the **Library** is how you mark them as such. Tables published to the Library's **Data** section appear _first_ when anyone picks a data source, nudging people toward your curated tables instead of raw warehouse ones. Lean: publish the wide clean tables you built the semantic layer on; hold back raw or half-built ones. Surface which tables you'd publish and confirm. (Only admins and data analysts can publish — mechanics in `core`.)
 <!-- /requires -->
@@ -102,7 +102,7 @@ Build each agreed definition. The verb mechanics (create/update flags, the `revi
 
 - **Segment** → `mb segment create`. A flat MBQL filter clause on a table.
 - **Measure** → `mb measure create`. **Exactly one** aggregation on a table.
-- **Metric** → `mb card create` with the metric shape (`type: "metric"`) — it lives in a **collection**, carries the aggregation plus an optional default time dimension. Put org-blessed ones in the Library collection.
+- **Metric** → `mb card create` with the metric shape (`type: "metric"`) — it lives in a **collection**, carries the aggregation plus an optional default time dimension. Put org-blessed ones in the Library's **Metrics** collection (id from `mb library get`).
 <!-- requires: library -->
 - **Publish the official tables** → `mb library create` then `mb library publish` (mechanics in `core`) to move the clean tables your definitions sit on into the Library's **Data** section, so people start from your curated set, not raw warehouse tables.
 <!-- /requires -->

package/skill-data/git-sync/SKILL.md

@@ -7,7 +7,7 @@ requires: [remoteSync]
 
 # git-sync (representations ↔ instance)
 
-Metabase content (cards, dashboards, transforms, snippets, collections, …) can live in a git repo as YAML and round-trip in and out of a Metabase instance via the `git-sync` verbs. The instance is configured with a `remote-sync-*` settings block (URL, branch, token, type read-only/read-write); the CLI drives the sync tasks against `/api/ee/remote-sync/*`. Only collections flagged for sync serialize; everything else is local-only. Table and field metadata round-trips too, for Library-published tables in a flagged collection — see "Published table metadata" below.
+Metabase content (cards, dashboards, transforms, snippets, collections, …) can live in a git repo as YAML and round-trip in and out of a Metabase instance via the `git-sync` verbs. The instance is configured with a `remote-sync-*` settings block (URL, branch, token, type read-only/read-write); the CLI drives the sync tasks against `/api/ee/remote-sync/*`. Only flagged collections serialize, plus, unflagged: each data app's collection (with its app, `data_apps/<slug>/`), transforms (`remote-sync-transforms`), and snippets, data actions and glossary once the Library is synced. Everything else is local-only. Table and field metadata round-trips too, for Library-published tables in a flagged collection — see "Published table metadata" below.
 
 The repo and the instance are two ends of the same state; what "push my changes" means depends on where the changes were made. If they were made **in the instance** (CLI verbs against a read-write instance — cards edited, transforms created, tables published, metadata written), "push my changes" / "save this to the repo" / "open a PR with these changes" means driving the instance's export to a branch (`stash` or `create-branch` + `export`) and opening the PR from that branch — not reconstructing the changes as files. If the workflow is **repo-first** (content YAML edited in the repo, the instance imports it), plain `git` against the repo is the way — but only in the serialized layout already there: files in paths or formats the serializer doesn't own are invisible to Metabase and never apply on import.
 
@@ -64,7 +64,7 @@ Workflow:
 
 <!-- requires: remoteSyncRemoteChanges -->
 
-Between the two, confirm `has-remote-changes` reports `has_changes: true` — there's actually something to import.
+Between the two, confirm `has-remote-changes` reports `has_changes: true` (`--force-refresh` after your own push: the answer is cached).
 
 <!-- /requires -->
 
@@ -168,7 +168,7 @@ Skip the prompt only if the user's instructions already specified the branch (e.
 ```bash
 mb git-sync branches --profile <n> --json                 # list remote branches
 mb git-sync create-branch <name> --profile <n>            # create + switch sync to it
-mb git-sync stash --profile <n>                           # export current state to a NEW branch
+mb git-sync stash --new-branch <name> --profile <n>       # export current state to a NEW branch
 ```
 
 `stash` is the safe move when the instance has team work you don't want to lose, but you need to pivot to a different branch (`import` would discard, `export --force` would overwrite). It exports current state to a fresh branch first.
@@ -184,19 +184,21 @@ Use `wait` after `import --no-wait` / `export --no-wait`. Use `cancel-task` if a
 
 ## Adding / removing a directory (collection) to sync
 
-The set of directories under sync is governed by which **collections** carry `is_remote_synced: true`. Every collection so flagged serializes to its own folder under `collections/` in the repo; everything outside that set is local-only. The CLI exposes per-collection toggles that route to the underlying bulk endpoint (`PUT /api/ee/remote-sync/settings`):
+The set of directories under sync is governed by which **collections** carry `is_remote_synced: true`. Every collection so flagged serializes to its own folder under `collections/` in the repo; so do the unflagged ones above (a data app's collection can't be flagged). Everything else is local-only. Toggle one collection at a time:
 
 ```bash
 mb git-sync add-collection    <collection-id> --profile <n> --json
 mb git-sync remove-collection <collection-id> --profile <n> --json
 ```
 
-`<collection-id>` is a **positive integer** (the bulk endpoint's schema is `pos-int? → boolean`; nano-id / `root` / `trash` refs are not supported). Get the id from `collection list` (see `core`).
+`<collection-id>` is a **positive integer** (no nano-id, `root` or `trash`). Get the id from `collection list` (see `core`).
 
-Both verbs return `{ success: true }`, plus a `task_id` only when the toggle started a follow-up task (e.g. a finalization import after switching to read-only).
+Both return `{ success: true }`, plus a `task_id` when the toggle started a follow-up task.
 
 **Cascade.** A toggle on a parent cascades to every descendant by `location` prefix — `add-collection 4` flips `4` plus every collection nested under it. `remove-collection 4` is the symmetric inverse. There is no per-leaf-only mode.
 
+**Custom collections.** Outside the Library, transforms, snippets and data actions, a flag answers 400 unless the admin setting `remote-sync-custom-collections-enabled` is on (a data app's collection can't be flagged at all).
+
 **Mode prerequisite.** The server rejects toggles while `remote-sync-type` is `:read-only` (the install default; `mb git-sync status --json` reports it as `sync_type`). If `mb git-sync add-collection 12` returns `Metabase returned 400 … Cannot change synced collections when remote-sync-type is read-only.`, switch first with:
 
 ```bash
@@ -237,13 +239,13 @@ To plan the order before the first move, `mb dependency graph dashboard <id> --j
 
 ## Published table metadata (Library) and sync scope
 
-Table and field metadata — table/field descriptions, semantic types (`type/PK`, `type/FK`), FK targets, plus segments and measures on the table — serializes for **Library-published tables only**, under `databases/<db>/schemas/<schema>/tables/<table>/…` in the repo. Eligibility is two-gated: the table must be published (`mb library publish`), **and** the Library collection holding it must itself carry `is_remote_synced: true`. An ordinary warehouse table, or a transform's target table that isn't published, never serializes — a transform's YAML carries only the transform definition (query, target, description), not the output table's field metadata.
+Table and field metadata — table/field descriptions, semantic types (`type/PK`, `type/FK`), FK targets, plus segments and measures on the table — serializes for **Library-published tables only**, under `databases/<db>/schemas/<schema>/tables/<table>/…` in the repo. Eligibility is two-gated: the table must be published (`mb library publish`), **and** Library Data must be synced; flag the Library root, as Data alone leaves out Metrics, Dashboards, snippets, data actions and glossary. An ordinary warehouse table, or a transform's target table that isn't published, never serializes — a transform's YAML carries only the transform definition (query, target, description), not the output table's field metadata.
 
-The classic trap: publish tables, write field metadata, then `git-sync dirty` comes back empty and nothing lands in the repo. That does not mean git-sync can't carry table metadata — it means the Library collection isn't in the sync scope, so nothing was eligible for dirty-tracking when the writes happened. Check the scope (`synced_collections` in `status`), then:
+The classic trap: publish tables, write field metadata, then `git-sync dirty` comes back empty and nothing lands in the repo. It means the Library collection isn't in the sync scope, so nothing was eligible for dirty-tracking when the writes happened. Check the scope (`synced_collections` in `status`), then:
 
 ```bash
-mb library get --profile <n> --json                                # Library Data collection id
-mb git-sync add-collection <library-data-id> --profile <n>
+mb collection list --profile <n> --json                            # the "type": "library" entry's id
+mb git-sync add-collection <library-id> --profile <n>
 mb git-sync stash --new-branch <branch> -m "..." --profile <n>     # or create-branch + export
 ```
 
@@ -256,7 +258,7 @@ Flagging the collection records it for the next export, which serializes its cur
 - Don't turn instance-side changes into hand-written repo files: export them and PR the exported branch (see the top of this skill). Files pushed behind Metabase's back race its own sync tasks.
 - Don't conclude from an empty `dirty` list that a change type isn't tracked. Dirty-tracking only records changes to _eligible_ objects; the usual cause is scope (the collection isn't flagged — see "Published table metadata"), not capability. Check `synced_collections` in `status` before concluding.
 - Don't run `git-sync import --force` or `git-sync export --force` without explicit user confirmation. Both are lossy — `--force` import discards instance-side work, `--force` export overwrites the remote branch.
-- Don't drive `git-sync` against a Metabase instance that doesn't have remote-sync configured — every verb returns an error pointing at the missing `remote-sync-*` settings. To check: `mb git-sync status --profile <n> --json` reports `remote_configured: false` when no remote is configured.
+- Don't drive `git-sync` against a Metabase instance that doesn't have remote-sync configured — import, export, has-remote-changes and export-preflight answer `Remote sync is not configured.` To check: `mb git-sync status --profile <n> --json` succeeds and reports `remote_configured: false`.
 - Don't author content directly via `card create` / `transform create` and then assume `git-sync export` will commit it cleanly — the instance and repo can drift if you mix direct API writes with sync-tracked changes. If you do, follow direct writes immediately with `git-sync export -m "..."` to keep them in step.
 - Don't move a dashboard or question into a synced collection before what it depends on, and don't retry a `Uses content that is not remote synced.` refusal unchanged. Move the listed dependencies first, move the whole containing collection, or build the content in the synced collection to begin with (see "Moving content into or out of a synced collection").
 - Don't omit `-m` on `export` if the user wants a meaningful commit message — the default server-generated message is generic.

package/skill-data/mbql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mbql
-description: Author and debug MBQL query bodies for the `mb` CLI — the query shape, clauses, filters, aggregation and breakout, order and limit, expressions, joins and FK columns, multi-stage pipelines, saved questions and definitions as sources, output column names, and the print-schema → dry-run → run loop. Use when writing or fixing any query body — `mb query`, a card's `dataset_query`, a transform's `source.query`, or a segment/measure `definition` — or when `--dry-run` or a run reports errors. Triggers — "write an MBQL query", "the dataset_query is wrong", "aggregate and group by", "join two tables", "month-over-month".
+description: Author and debug MBQL query bodies for the `mb` CLI — the query shape, clauses, filters, aggregation and breakout, order and limit, expressions, joins and FK columns, multi-stage pipelines, saved questions and definitions as sources, output column names, and the schema → dry-run → run loop. Use when writing or fixing any query body — `mb query`, a card's `dataset_query`, a transform's `source.query`, or a segment/measure `definition` — or when `--dry-run` or a run reports errors. Triggers — "write an MBQL query", "the dataset_query is wrong", "aggregate and group by", "join two tables", "month-over-month".
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -147,12 +147,12 @@ A measure is an aggregation, `["measure", {}, <measure id>]`, on its table, and
 
 <!-- /requires -->
 
-## Authoring loop: print-schema → dry-run → run
+## Authoring loop: schema → dry-run → run
 
 ```bash
 mb query --file q.json --dry-run --profile <n>        # check + compile on the server, no run
 mb query --file q.json --profile <n> --json           # check + run
-mb query --print-schema --profile <n> > ./.scratch/mbql-schema.json   # the full JSON Schema
+mb schema query > ./.scratch/mbql-schema.json         # the JSON Schema bundle, no server needed
 mb query --file q.json --compile --profile <n>        # the SQL the server generates
 mb query --file q.json --metadata --profile <n> --json   # tables (with FK targets), fields, snippets it touches
 mb query --file q.json --export-format csv --profile <n> > rows.csv   # stream the rows up to the server's download limit, no envelope cap

package/skill-data/native-sql/SKILL.md

@@ -28,7 +28,7 @@ A native `dataset_query` is a query with one **native stage** — the `lib/type:
 }
 ```
 
-This is the form a card stores and returns — author it. The CLI **pre-flight-validates** it — the envelope, the template-tag shapes, the field refs — through the usual `--print-schema → --dry-run → run` loop (`mbql`), and a saved card **round-trips** in exactly this shape: `mb card get <id> --full --json`, edit the `stages[0].native` string, send it straight back. Only the warehouse parses the SQL string, so a **SQL** syntax error surfaces when you run it, not at `--dry-run`. A parameterless query needs no `template-tags` — just the `native` string.
+Author it in this form. The CLI **pre-flight-validates** it — the envelope, the template-tag shapes, the field refs — through the usual `mb schema query` → `--dry-run` → run loop (`mbql`). A saved card **round-trips**: `mb card get <id> --full --json` returns the same stage with `template-tags` as a list of the same entries, each carrying its `name`; edit the `stages[0].native` string and send it straight back, list and all. Only the warehouse parses the SQL string, so a **SQL** syntax error surfaces when you run it, not at `--dry-run`. A parameterless query needs no `template-tags` — just the `native` string.
 
 You may see an older flat form in cards created long ago — `{database, type:"native", native:{query}}`. The server still accepts it (it normalizes to the above) but it skips pre-flight and doesn't round-trip — **don't author it**.
 

package/skill-data/native-sql/references/template-tags.md

@@ -4,7 +4,7 @@ Every template-tag body, the widget-type vocabulary, and the parameter-object sh
 
 ## Template-tag bodies by `type`
 
-The `template-tags` value is a map keyed by tag name; each entry's `name` must equal its key and the `{{name}}` in the SQL. `id` is any string unique among the tags; the tag's name serves.
+Author the `template-tags` value as a map keyed by tag name; each entry's `name` must equal its key and the `{{name}}` in the SQL. A card read back carries the same entries as a list, which the server also takes. `id` is any string unique among the tags; the tag's name serves.
 
 ### Raw variable — `text` / `number` / `date` / `boolean`
 

package/dist/api-key-wGtJ8kYy.mjs

@@ -1,13 +0,0 @@
-import { t as defineCommandGroup } from "./group-81zoQcEP.mjs";
-//#region src/commands/api-key/index.ts
-var api_key_default = defineCommandGroup({
-	name: "api-key",
-	description: "Manage Metabase API keys",
-	subCommands: {
-		list: () => import("./list-s9_LlXCV.mjs").then((mod) => mod.default),
-		create: () => import("./create-C3H9ljex.mjs").then((mod) => mod.default),
-		delete: () => import("./delete-4v4_lDwD.mjs").then((mod) => mod.default)
-	}
-});
-//#endregion
-export { api_key_default as default };