@metabase/cli 0.5.4 → 0.5.6

package/dist/{update-dashcard-BijqiYQd.mjs → update-dashcard-fWxyfSG5.mjs}

@@ -1,6 +1,6 @@
 import { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
 import { t as parseId } from "./parse-id-EXZan40V.mjs";
-import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
 import { t as bodyInputFlags } from "./body-flags-AqKpN01Y.mjs";
 import { h as DashcardPatchInput, m as DashcardDetail } from "./dashboard-Cwsf-e9T.mjs";
 import { r as dashcardView } from "./dashboard-Bx2sYijR.mjs";

package/dist/{update-7iXRB23T2.mjs → update-eL6rSQvo2.mjs}

@@ -1,6 +1,6 @@
 import { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
 import { t as parseId } from "./parse-id-EXZan40V.mjs";
-import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
 import { t as bodyInputFlags } from "./body-flags-AqKpN01Y.mjs";
 import { o as TransformJobUpdateInput, t as TransformJob } from "./transform-job-CDIb3B9o.mjs";
 import { t as transformJobView } from "./transform-job-D18XRLBK.mjs";

package/dist/{update-552UGPAG.mjs → update-nZkZHbL5.mjs}

@@ -1,6 +1,6 @@
 import { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
 import { t as parseId } from "./parse-id-EXZan40V.mjs";
-import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
 import { t as bodyInputFlags } from "./body-flags-AqKpN01Y.mjs";
 import { a as PulseUpdateInput, t as Pulse } from "./pulse-B2AmIWsO.mjs";
 import { t as pulseView } from "./pulse-CPSpum5U.mjs";

package/dist/{update-DVD77mVR.mjs → update-zKgO1dbJ.mjs}

@@ -1,6 +1,6 @@
 import { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
 import { t as parseId } from "./parse-id-EXZan40V.mjs";
-import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
 import { t as bodyInputFlags } from "./body-flags-AqKpN01Y.mjs";
 import { c as TimelineUpdateInput, t as Timeline } from "./timeline-DcsCXNUt.mjs";
 import { n as timelineView } from "./timeline-BgWz8DYK.mjs";

package/dist/{upgrade-TzILOkiM.mjs → upgrade-PIUDxb6V.mjs}

@@ -1,7 +1,6 @@
 import { g as errorMessage, i as AbortError, m as UnknownError, p as TimeoutError, u as NetworkError } from "./predicates-0C0TsWcJ.mjs";
 import { K as HttpError, X as parseJson, lt as outputFlags, nt as name, o as renderItem, p as writeText, rt as version, t as interruptSignal, v as promptConfirm } from "./cli.mjs";
-import { E as USER_AGENT, t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
-import { n as throwIfAborted, t as combineAborts } from "./signal-BNUlQjpc.mjs";
+import { E as USER_AGENT, U as combineAborts, W as throwIfAborted, t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
 import { n as streamProcess } from "./process-BQC3mK2k.mjs";
 import { z } from "zod";
 import { realpathSync } from "node:fs";

package/dist/{upload-Do-kOGtc.mjs → upload-B6S0Vqgn.mjs}

@@ -1,7 +1,7 @@
 import { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
-import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
 import { t as ContentTranslationUploadResult } from "./content-translation-BrHOrmj9.mjs";
-import { n as requireUploadFilePath, t as readCsvFile } from "./upload-CdiDKe69.mjs";
+import { n as requireUploadFilePath, t as readCsvFile } from "./upload-KuHgzGJU.mjs";
 //#region src/output/views/content-translation.ts
 const contentTranslationUploadView = {
 	compactPick: ContentTranslationUploadResult,

package/dist/{upload-B37bUVl_.mjs → upload-Dzn5OAbv.mjs}

@@ -4,9 +4,9 @@ var upload_default = defineCommandGroup({
 	name: "upload",
 	description: "Upload CSV files into Metabase",
 	subCommands: {
-		csv: () => import("./csv-LP7sE-CS.mjs").then((m) => m.default),
-		append: () => import("./append-BPrVW4RB.mjs").then((m) => m.default),
-		replace: () => import("./replace-DoU0IFGd.mjs").then((m) => m.default)
+		csv: () => import("./csv-D50rzoTk.mjs").then((m) => m.default),
+		append: () => import("./append-DHsRfdyS.mjs").then((m) => m.default),
+		replace: () => import("./replace-D3I8Cb6E.mjs").then((m) => m.default)
 	}
 });
 //#endregion

package/dist/{upload-CdiDKe69.mjs → upload-KuHgzGJU.mjs}

@@ -1,5 +1,5 @@
 import { o as ConfigError, v as isFileNotFoundError } from "./predicates-0C0TsWcJ.mjs";
-import { D as fileNotFoundError } from "./runtime-iIsqiOwO.mjs";
+import { D as fileNotFoundError } from "./runtime-CEAFobLj.mjs";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 //#region src/runtime/upload.ts

package/dist/{uuid-Dqq2WfAT.mjs → uuid-BPr2deuu.mjs}

@@ -1,6 +1,6 @@
 import { o as ConfigError } from "./predicates-0C0TsWcJ.mjs";
 import { f as writeJson, lt as outputFlags, mt as parseInteger, p as writeText } from "./cli.mjs";
-import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 //#region src/commands/uuid.ts

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

@@ -1,6 +1,6 @@
 import { h as formatScalar, it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
 import { t as parseId } from "./parse-id-EXZan40V.mjs";
-import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
 import { d as FieldValues } from "./field-C2qOViFZ.mjs";
 import { s as fieldValuesView } from "./field-CT4r6b92.mjs";
 //#region src/commands/field/values.ts

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

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

package/dist/{verify-DJ7fGyLL.mjs → verify-D9i63gmK.mjs}

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

package/dist/{verify-BiB8jzXB.mjs → verify-DS0REVed.mjs}

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

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

@@ -1,7 +1,7 @@
 import { it as connectionFlags, l as renderSummary, lt as outputFlags, ut as profileFlag } from "./cli.mjs";
-import { t as defineMetabaseCommand } from "./runtime-iIsqiOwO.mjs";
-import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-vxN__4cz.mjs";
-import { r as parseWaitSchedule } from "./wait-flags-C3cu_O0w.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CEAFobLj.mjs";
+import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-uailHW3t.mjs";
+import { r as parseWaitSchedule } from "./wait-flags-DT1zA69Z.mjs";
 import { u as syncTaskView } from "./git-sync-D1aKczo6.mjs";
 import { a as throwIfFailedTask, i as taskPollOptions, n as formatSyncTask, r as syncTaskIdleView, t as SyncTaskOrIdle } from "./sync-task-Gf86CU9l.mjs";
 //#region src/commands/git-sync/wait.ts

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metabase/cli",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Metabase CLI",
   "license": "AGPL-3.0",
   "repository": {

package/skill-data/core/SKILL.md

@@ -156,7 +156,7 @@ What `--help` doesn't say: footguns and non-obvious behaviors.
 - **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 -->
@@ -165,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** with `mb skills get <name>` — don't wing an MBQL body, a transform body, or the git-sync workflow from this overview.
+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).
@@ -185,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/`, `build/`, `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 `build/index.js`, the file `npm run build` writes (`--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 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 those two, and leave them out of your commits unless the bundle ships through git (below). The template's `.gitignore` keeps `node_modules/`, `build/` and `.env.local` out. A bundle can instead ship through git, from CI say: `npm run build:ci` writes `dist/index.js`, and once that is committed and pushed, the next import loads it. 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
@@ -20,10 +20,14 @@ npm install
 ```bash
 npm run dev         # preview at http://localhost:5174, in the sandbox Metabase runs apps in
 npm run typecheck   # type-checks src/ and vite.config.ts
-npm run build       # builds dist/index.js
+npm run build       # builds build/index.js
 mb data-app typed-schema <slug> --out src/metabase.ts   # the app's queries and actions
-mb data-app set-bundle <slug>                     # makes dist/index.js the app's bundle
+mb data-app set-bundle <slug>                     # makes build/index.js the app's bundle
 ```
 
+To ship the bundle through git instead, for example from CI, run
+`npm run build:ci` and commit `dist/index.js`, the file the app's
+`data_app.yaml` names; the next git-sync import loads it.
+
 `npm run dev` reads `DATA_APP_MB_URL` and `DATA_APP_MB_API_KEY` from
 `.env.local`; `.env.local.example` lists them.

package/skill-data/data-app/template/gitignore

@@ -1,5 +1,5 @@
 node_modules
-dist
+build
 .env.local
 .vite
 .idea

package/skill-data/data-app/template/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
+    "build:ci": "vite build --outDir dist",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

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 -->