@metabase/cli 0.1.16 → 0.1.18

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

@@ -0,0 +1,178 @@
+# Template tags — full reference
+
+Every template-tag body, the widget-type vocabulary, and the parameter-object shapes. The main skill covers the two you author most (field filter, raw variable); this is the rest plus the exhaustive field lists.
+
+## 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 a UUID — mint with `mb uuid`.
+
+### Raw variable — `text` / `number` / `date` / `boolean`
+
+```json
+"min_total": {
+  "id": "<uuid>",
+  "name": "min_total",
+  "display-name": "Minimum total",
+  "type": "number",
+  "required": false,
+  "default": "50"
+}
+```
+
+| Field          | Req | Notes                                        |
+| -------------- | --- | -------------------------------------------- |
+| `name`         | ✓   | equals map key and `{{name}}`                |
+| `display-name` | ✓   | label shown in the widget                    |
+| `type`         | ✓   | `text` \| `number` \| `date` \| `boolean`    |
+| `id`           | —   | UUID; supply one                             |
+| `required`     | —   | `true` blocks the run until a value is given |
+| `default`      | —   | value used when none passed (string form)    |
+
+SQL: `{{min_total}}`, spliced literally — you write the operator (`total > {{min_total}}`).
+
+### Field filter — `dimension`
+
+```json
+"status": {
+  "id": "<uuid>",
+  "name": "status",
+  "display-name": "Status",
+  "type": "dimension",
+  "dimension": ["field", {}, 141],
+  "widget-type": "string/=",
+  "default": null,
+  "options": null,
+  "alias": null
+}
+```
+
+| Field         | Req | Notes                                                                                                                                                  |
+| ------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `type`        | ✓   | `"dimension"`                                                                                                                                          |
+| `dimension`   | ✓   | field ref `["field", {}, <id>]` — options object second, id third (the `mbql` rule); the legacy `["field", <id>, null]` form is rejected by pre-flight |
+| `widget-type` | ✓   | the widget/operator; must suit the column type (table below)                                                                                           |
+| `default`     | —   | e.g. a value, or a `["2024-01-01","2024-12-31"]` range                                                                                                 |
+| `options`     | —   | filter options map (e.g. case sensitivity), usually `null`                                                                                             |
+| `alias`       | —   | set when the column comes from an aliased table in the SQL                                                                                             |
+
+SQL: bare — `WHERE {{status}}`. Never `WHERE status = {{status}}`. On write, send `{}` for the ref's options; the server fills a `lib/uuid` and the card reads back `["field", {"lib/uuid": "…"}, <id>]`.
+
+### Snippet — `snippet`
+
+```json
+"snippet: Active Rows": {
+  "id": "<uuid>",
+  "name": "snippet: Active Rows",
+  "display-name": "Snippet: Active Rows",
+  "type": "snippet",
+  "snippet-name": "Active Rows",
+  "snippet-id": 5
+}
+```
+
+SQL: `{{snippet: Active Rows}}`. Create/manage the fragment with `mb snippet` (`content` is bare SQL). No user value.
+
+### Card reference — `card`
+
+```json
+"#42": {
+  "id": "<uuid>",
+  "name": "#42",
+  "display-name": "#42",
+  "type": "card",
+  "card-id": 42
+}
+```
+
+SQL: `{{#42}}` or `{{#42-slug}}`, used where a table/subquery goes (`FROM {{#42}}`, `WITH x AS {{#42}}`). Runs with the referenced card's own defaults; no user value.
+
+### Source table — `table` (v59+)
+
+A niche v59+ type that references a warehouse table by id (`{type: "table", table-id: <id>}`, optional `source-filters`) where a table/subquery goes — analogous to a card reference but pointing at a raw table. Absent on v0.58. Reach for a card reference (`card`) unless you specifically need a bare-table source tag.
+
+### Temporal unit — `temporal-unit`
+
+A widget that lets the viewer pick the time bucket (day/week/month/…) for a datetime column. Body mirrors a field filter (`dimension` legacy ref, optional `alias`) with `type: "temporal-unit"`.
+
+## `widget-type` by column type
+
+Closed enum — same vocabulary as a dashboard parameter `type`. Pick one whose family matches the bound column.
+
+| Column type                            | Common widget-types                                                                                                   |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Text / string                          | `string/=` `string/!=` `string/contains` `string/does-not-contain` `string/starts-with` `string/ends-with` `category` |
+| Number                                 | `number/=` `number/!=` `number/between` `number/>=` `number/<=`                                                       |
+| Date / datetime                        | `date/all-options` `date/single` `date/range` `date/relative` `date/month-year` `date/quarter-year`                   |
+| Boolean                                | `boolean/=`                                                                                                           |
+| ID / FK                                | `id`                                                                                                                  |
+| Location (with matching semantic type) | `location/city` `location/state` `location/zip_code` `location/country`                                               |
+
+`date/all-options` gives the fullest date picker (single, range, relative). `category` yields a value-list dropdown for a low-cardinality text column.
+
+## Parameter object — declared vs. runtime
+
+Same object, two contexts. `target` links the parameter to a template tag: `["dimension", ["template-tag", "<name>"]]` for a field filter, `["variable", ["template-tag", "<name>"]]` for a raw variable.
+
+**Declared** — in the card's `parameters` array, to set a default or a dropdown source:
+
+```json
+{
+  "id": "<uuid>",
+  "name": "status",
+  "slug": "status",
+  "type": "string/=",
+  "target": ["dimension", ["template-tag", "status"]],
+  "default": "active",
+  "values_source_type": "static-list",
+  "values_source_config": { "values": ["active", "churned", "trial"] }
+}
+```
+
+`values_source_type`: omit to pull live distinct values from the bound field; `"static-list"` + `values_source_config.values` for a fixed list; `"card"` + `{card_id, value_field, label_field}` to source from a query.
+
+**Runtime** — passed to `card query --parameters`; carries a `value`, no source config:
+
+```json
+{ "type": "string/=", "target": ["dimension", ["template-tag", "status"]], "value": "active" }
+```
+
+The runtime `type` is the value's type, not the tag's. Date ranges pass as `"value": ["2024-01-01", "2024-12-31"]`. Omit a parameter entirely to leave an optional (`[[ ]]`) clause out.
+
+## Full native card body
+
+What `mb card create --file` consumes:
+
+```json
+{
+  "name": "Active orders by status",
+  "display": "table",
+  "visualization_settings": {},
+  "dataset_query": {
+    "lib/type": "mbql/query",
+    "database": 1,
+    "stages": [
+      {
+        "lib/type": "mbql.stage/native",
+        "native": "SELECT status, count(*) FROM orders WHERE total > {{min_total}} [[AND {{status}}]] GROUP BY status",
+        "template-tags": {
+          "min_total": {
+            "id": "<uuid>",
+            "name": "min_total",
+            "display-name": "Minimum total",
+            "type": "number",
+            "default": "0"
+          },
+          "status": {
+            "id": "<uuid>",
+            "name": "status",
+            "display-name": "Status",
+            "type": "dimension",
+            "dimension": ["field", {}, 141],
+            "widget-type": "string/="
+          }
+        }
+      }
+    ]
+  }
+}
+```

package/skill-data/transform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: transform
-description: Author and run Metabase transforms via `mb` — body shape (native SQL + MBQL 5), create + run-with-wait, run inspection, dependencies, cancel, the `update`-vs-recreate iteration rule, the writable-keys-only PATCH contract, plus transform tags and tag-driven transform-job schedules. Load when the user touches transforms — "create a transform", "run a transform", "fix a failing transform", "list transform runs", "cancel a running transform", "manage transform tags", "run a transform job", or anything `mb transform …` / `mb transform-job …` / `mb transform-tag …`.
+description: Author and run Metabase transforms via `mb` — body shape (native SQL or structured MBQL), create + run-with-wait, run inspection, dependencies, cancel, the `update`-vs-recreate iteration rule, the writable-keys-only PATCH contract, plus transform tags and tag-driven transform-job schedules. Load when the user touches transforms — "create a transform", "run a transform", "fix a failing transform", "list transform runs", "cancel a running transform", "manage transform tags", "run a transform job", or anything `mb transform …` / `mb transform-job …` / `mb transform-tag …`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 A **transform** persists the result of a query (native SQL or MBQL) to a warehouse table the user can read from cards, dashboards, and other transforms. It runs on a schedule (via `transform-job`) or on-demand (`transform run`).
 
-Flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`). Deciding _which_ transforms to build — modeling a whole raw database into a set of clean, analysis-ready tables — is the `data-transformation` skill (`mb skills get data-transformation`).
+Flag conventions, body-input precedence, and the `./.scratch` convention live in `core` (`mb skills get core`). Deciding _which_ transforms to build — modeling a whole raw database into clean, analysis-ready tables — is the `data-workflow` skill's build-clean-tables stage (`mb skills get data-workflow`).
 
 ## Body shape
 
@@ -17,14 +17,13 @@ A transform has two halves:
 - `source` — the query to run (`type: "query"`, with `query.type` of `native` or `mbql`).
 - `target` — the warehouse destination (`type: "table"`, with `database`, `schema`, `name`).
 
-Native SQL is the simplest source and the easiest to author by hand. MBQL is what the Metabase UI emits and is more verbose; pull a sample with `mb transform get <id> --full --json` if you need its shape.
-
-For an **MBQL 5** `source.query` (`lib/type: "mbql/query"`), the body shape, the "options object is always second" clause rule, UUID minting, aggregation/order-by refs, naming aggregation output columns, and the `--print-schema` → `--dry-run` validation loop are all in the `mbql` skill — **`mb skills get mbql`**. The MBQL-5 pre-flight on `transform create`/`update` is documented there too (legacy MBQL 4 and native sources skip it). For a transform target, naming your aggregation output columns matters more than usual — a bare `count` / `avg_2` becomes the warehouse column name; see the `mbql` skill's "Naming aggregation output columns".
+Native SQL is the simplest source — author it as an `mbql.stage/native` stage (the SQL string sits at `source.query.stages[0].native`), the form below. For a **structured** `source.query` (an `mbql.stage/mbql` stage) — the options-object-is-always-second clause rule, UUID minting, aggregation/order-by refs, naming aggregation output columns, and the `--print-schema` → `--dry-run` validation loop — see `mbql` (**`mb skills get mbql`**). Both stage types are the `mbql/query` shape, so `transform create`/`update` pre-flight them (only the legacy flat forms skip it). Pull a sample body with `mb transform get <id> --full --json`. For a transform target, naming aggregation output columns matters more than usual: a bare `count` / `avg_2` becomes the warehouse column name.
 
 ## Create + run (native SQL)
 
+**Keep the SQL formatted.** Author it multi-line in `./.scratch/<name>.sql` and embed with `jq --rawfile` (jq ≥1.6, which JSON-encodes the file so newlines become `\n`). The stored SQL (`source.query.stages[0].native`) is what `mb transform get` and the Metabase editor render — a single-line blob is valid JSON but unreadable when anyone opens the transform. Single-quote the heredoc delimiter (`<<'SQL'`) so the shell leaves `$vars` in the query alone (e.g. Postgres `$1`, `$$`).
+
 ```bash
-# Author the SQL formatted — it's what `mb transform get` and the Metabase editor show.
 cat > ./.scratch/user_counts_by_signup_year.sql <<'SQL'
 SELECT
   date_trunc('year', created_at)::date AS signup_year,
@@ -34,11 +33,10 @@ GROUP BY 1
 ORDER BY 1
 SQL
 
-# Embed it with jq --rawfile so the newlines survive as \n in valid JSON (don't hand-write the SQL as one line).
 jq -n --rawfile q ./.scratch/user_counts_by_signup_year.sql \
   '{ name: "user_counts_by_signup_year",
      description: "Sample transform: counts users by year of signup",
-     source: { type: "query", query: { type: "native", database: <db-id>, native: { query: $q } } },
+     source: { type: "query", query: { "lib/type": "mbql/query", database: <db-id>, stages: [{ "lib/type": "mbql.stage/native", native: $q }] } },
      target: { type: "table", database: <db-id>, schema: "public", name: "user_counts_by_signup_year" } }' \
   > ./.scratch/transform.json
 
@@ -46,17 +44,13 @@ TRANSFORM_ID=$(mb transform create --file ./.scratch/transform.json --profile <n
 mb transform run "$TRANSFORM_ID" --wait --profile <name> --json
 ```
 
-Notes:
-
-- `<db-id>` comes from `mb database list --profile <name> --json`. Database ids are per-instance.
-- Target `schema` is the schema the result table is written into (e.g. `public`).
-- `--wait` on `transform run` polls until status is `succeeded` or `failed`. Without it you only get `{message: "Transform run started", run_id, final: null}` and have to poll yourself.
-- `--sync` implies `--wait`, then waits until the run's output table is registered — the run registers it itself, no `db sync-schema` needed — adding `target_table_id` to the envelope. Use it when you'll build MBQL on the output (see "Inspect").
-- The `--json` envelope is shape-stable: `{message, run_id, final}` (plus `target_table_id` under `--sync` — a number, or `null` if the table didn't register before the timeout). `final` is `null` when `--wait` is omitted or the run never started, otherwise a full `TransformRun` object with `status` and `message`. On a failed run (`final.status` ∈ {`failed`, `timeout`, `canceled`}) the CLI exits 1 and writes a one-line summary `transform run <id> failed` to stderr; the failure detail lives only in `final.message` on stdout, so `jq -r '.final.message'` is where to look.
-- **Keep the SQL formatted.** Author it multi-line in `./.scratch/<name>.sql` and embed with `jq --rawfile` (jq ≥1.6, which JSON-encodes the file so newlines become `\n`). The stored `native.query` is what `mb transform get` and the Metabase editor render — a single-line blob is valid JSON but unreadable when anyone opens the transform. Single-quote the heredoc delimiter (`<<'SQL'`) so the shell leaves `$vars` in the query alone (e.g. Postgres `$1`, `$$`).
-- `transform create --json` returns the agent-facing compact projection: `{id, name, description, source_type, target: {type, database, schema, name}, target_db_id}`. Read `target.schema`/`target.name` directly off the create output — no follow-up `transform get` needed to verify where the transform will write.
-- If a transform with the same `name` already has a YAML representation on disk under the configured remote-sync repo, `create` mints a `_2` suffix on the exported filename (the new transform gets a fresh `entity_id`; the prior one isn't touched). For "iterate on the same concept" workflows, prefer `transform update <id>` — see "Iterating on a failing transform" below.
-- **`collection_id` only accepts a collection in the `:transforms` namespace.** Transforms aren't filed next to cards and dashboards — passing a normal analytics collection id (the kind a dashboard lives in) fails create/update with `collection_id: A Transform can only go in Collections in the :transforms namespace.` Omit `collection_id` to leave the transform uncollected (the common case), or create one with `mb collection create --body '{"name":"…"}' --namespace transforms --json` and pass the returned `id`. Cards and dashboards you build **on top of** the transform's output table go in ordinary collections as usual — so "put the transform and its dashboard in collection X" generally means _X holds the dashboard + cards; the transform stays in the transforms namespace._
+- `<db-id>` comes from `mb database list --profile <name> --json`; ids are per-instance. Target `schema` is the schema the result table is written into (e.g. `public`).
+- `--wait` polls until status is `succeeded` or `failed`. Without it you get only `{message: "Transform run started", run_id, final: null}` and must poll yourself — don't put bare `transform run` in a tight loop; let `--wait` do the polling.
+- `--sync` implies `--wait`, then waits until the run registers its output table (the run registers it itself — no `db sync-schema` needed), adding `target_table_id` to the envelope. Use it when you'll build MBQL on the output (see "Inspect").
+- The `--json` envelope is shape-stable: `{message, run_id, final}` (plus `target_table_id` under `--sync` — a number, or `null` if the table didn't register before the timeout). `final` is `null` when `--wait` is omitted or the run never started, otherwise a full `TransformRun` with `status` and `message`. On a failed run (`final.status` ∈ {`failed`, `timeout`, `canceled`}) the CLI exits 1 and writes a one-line `transform run <id> failed` to stderr; the failure detail lives only in `final.message` on stdout, so `jq -r '.final.message'` is where to look.
+- `transform create --json` returns the agent-facing compact projection: `{id, name, description, source_type, target: {type, database, schema, name}, target_db_id}`. Read `target.schema`/`target.name` directly off it — no follow-up `transform get`.
+- If a transform with the same `name` already has a YAML representation on disk under the configured remote-sync repo, `create` mints a `_2` suffix on the exported filename (the new transform gets a fresh `entity_id`; the prior one isn't touched). For "iterate on the same concept", prefer `transform update <id>` — see "Iterating on a failing transform".
+- **`collection_id` only accepts a collection in the `:transforms` namespace.** Transforms aren't filed next to cards and dashboards — a normal analytics collection id fails create/update with `collection_id: A Transform can only go in Collections in the :transforms namespace.` Omit `collection_id` to leave the transform uncollected (the common case), or provision one with `mb collection create --body '{"name":"…"}' --namespace transforms --json` (see `core`) and pass the returned `id`. Cards and dashboards you build **on top of** the output table go in ordinary collections — so "put the transform and its dashboard in collection X" means _X holds the dashboard + cards; the transform stays in the transforms namespace._
 
 ## Inspect
 
@@ -66,7 +60,7 @@ mb transform get <id> --profile <name> --full --json          # full transform i
 mb transform dependencies <id> --profile <name> --json        # upstream transforms this one must run after
 ```
 
-After a run the table physically exists in the warehouse, but Metabase addresses tables/columns by numeric id, so **MBQL and the UI can't reference a brand-new table until the instance syncs** (native SQL — a native `card` or `mb query` against `<schema>.<name>` — reads it immediately). Run and register in one step with `--sync`.
+After a run the table physically exists in the warehouse, but Metabase addresses tables/columns by numeric id, so **MBQL and the UI can't reference a brand-new table until the instance syncs** (native SQL — a native `card` or `mb query` against `<schema>.<name>` — reads it immediately). Run and register in one step with `--sync`:
 
 ```bash
 TABLE_ID=$(mb transform run <id> --sync --profile <name> --json | jq -r '.target_table_id')
@@ -91,12 +85,10 @@ mb transform get-run <run-id> --profile <name> --json
 mb transform cancel <id> --profile <name> --json
 ```
 
-Notes:
-
 - `transform runs` and `transform get-run` parse against the same `TransformRun` schema, so `get-run` returns the same per-run shape as one entry of `runs`. The compact projection is `{id, transform_id, status, run_method, start_time, end_time, message}`. Pass `--full` on `get-run` for the hydrated row including `is_active`, `user_id`, `transform_name`, `transform_entity_id`, `checkpoint_*` fields, and a nested `transform: {id, name, …}` block.
-- `transform cancel` takes the **transform** id and 404s with `Endpoint not found — is this a Metabase instance?` if there is no active run. The response shape is `{canceled: true, id: <transform-id>}`.
-- For native-SQL transforms, cancel marks the run as `canceling` but does **not** kill the warehouse query mid-flight — the query runs to completion, then the run lands as `canceled` (or stays `succeeded` if the cancel arrived after the writer committed). For Python transforms the worker is interrupted directly. Don't expect cancel to free warehouse resources instantly on long native queries; expect it to flip state and prevent downstream consumers from treating the result as good.
-- The `--transform-id` filter on `runs` accepts a single integer; the CLI translates to the server's `transform-ids` query vector. To cross-filter multiple transforms, run `transform runs --json` and `jq` post-hoc.
+- `transform cancel` takes the **transform** id and returns `{canceled: true, id: <transform-id>}`. It 404s with `Endpoint not found — is this a Metabase instance?` if there is no active run.
+- **Cancel semantics differ by source.** For native SQL, cancel marks the run `canceling` but does **not** kill the warehouse query mid-flight — the query runs to completion, then the run lands as `canceled` (or stays `succeeded` if the cancel arrived after the writer committed). For Python transforms the worker is interrupted directly. Don't expect cancel to free warehouse resources instantly on long native queries; expect it to flip state and prevent downstream consumers from treating the result as good.
+- The `--transform-id` filter on `runs` accepts a single integer (translated to the server's `transform-ids` vector). To cross-filter multiple transforms, run `transform runs --json` and `jq` post-hoc.
 
 ## Update body: send only writable keys, never round-trip the GET body
 
@@ -107,7 +99,7 @@ name, description, source, target, run_trigger,
 tag_ids, collection_id, owner_user_id, owner_email
 ```
 
-**Don't paste the output of `transform get` into a `transform update` body.** The GET response carries server-side fields (`id`, `entity_id`, `created_at`, `updated_at`, `creator_id`, `last_run`, `target_db_id`, `target_table_id`, `source_type`, `source_database_id`, `source_readable`, `creator`, `owner`, `table`, …) that the PUT endpoint isn't built to handle. Unknown top-level keys flow into `t2/update!` and produce a leaked H2 SQL error like:
+**Never paste the output of `transform get` into a `transform update` body.** The GET response carries server-side fields (`id`, `entity_id`, `created_at`, `updated_at`, `creator_id`, `last_run`, `target_db_id`, `target_table_id`, `source_type`, `source_database_id`, `source_readable`, `creator`, `owner`, `table`, …) that the PUT endpoint isn't built to handle. Unknown top-level keys flow into `t2/update!` and leak a raw H2 SQL error like:
 
 ```
 Column "TAGS" not found; SQL statement:
@@ -116,11 +108,11 @@ UPDATE "TRANSFORM" SET "TAGS" = (), "UPDATED_AT" = NOW() WHERE "ID" = ? [42122-2
 
 Three specific footguns:
 
-- **`tags` is not a key on the REST API.** The serdes/YAML representation uses `tags`; the REST contract uses `tag_ids` (an array of integer ids). If you pulled a YAML representation and want to PUT it, translate `tags: [...]` → `tag_ids: [...]` first (or omit it entirely if you're not changing tag membership).
+- **`tags` is not a REST key.** The serdes/YAML representation uses `tags`; the REST contract uses `tag_ids` (an array of integer ids). If you pulled a YAML representation and want to PUT it, translate `tags: [...]` → `tag_ids: [...]` first (or omit it if you're not changing tag membership).
 - **`source_type`, `target_db_id`, `target_table_id`, `entity_id`** are derived/computed by the server. They appear in GET responses for the agent's benefit; the server doesn't accept them on update.
-- **`collection_id` must be a `:transforms`-namespace collection** — a regular card/dashboard collection id is rejected with `A Transform can only go in Collections in the :transforms namespace.` Omit it unless you have one (see the create notes above). Round-tripping the existing value is safe; setting it to an ordinary collection is what fails.
+- **`collection_id` must be a `:transforms`-namespace collection** — a regular card/dashboard collection id is rejected with `A Transform can only go in Collections in the :transforms namespace.` Round-tripping the existing value is safe; setting it to an ordinary collection is what fails.
 
-Right shape — patch only what changes:
+Patch only what changes:
 
 ```bash
 # Rename only:
@@ -132,7 +124,7 @@ SELECT …
 FROM public.orders
 SQL
 jq -n --rawfile q ./.scratch/orders.sql \
-  '{ source: { type: "query", query: { type: "native", database: <db-id>, native: { query: $q } } } }' \
+  '{ source: { type: "query", query: { "lib/type": "mbql/query", database: <db-id>, stages: [{ "lib/type": "mbql.stage/native", native: $q }] } } }' \
   > ./.scratch/patch.json
 mb transform update <id> --file ./.scratch/patch.json --profile <name> --json
 
@@ -140,7 +132,7 @@ mb transform update <id> --file ./.scratch/patch.json --profile <name> --json
 mb transform update <id> --body '{"tag_ids":[1,3]}' --profile <name> --json
 ```
 
-`tag_ids` are the integer ids of **transform tags** — discover and manage them with the `transform-tag` group: `mb transform-tag list --json` (find ids; the four built-ins `hourly`/`daily`/`weekly`/`monthly` are seeded), `mb transform-tag create --body '{"name":"nightly"}' --json`, `mb transform-tag update <id>`, `mb transform-tag delete <id>`. Tags are also how a `transform-job` selects what to run — a job executes every transform carrying one of the job's tags (see "Transform jobs" below).
+`tag_ids` are the integer ids of **transform tags** — manage them with the `transform-tag` group: `mb transform-tag list --json` (find ids; the four built-ins `hourly`/`daily`/`weekly`/`monthly` are seeded), `mb transform-tag create --body '{"name":"nightly"}' --json`, `mb transform-tag update <id>`, `mb transform-tag delete <id>`. Tags are also how a `transform-job` selects what to run — a job executes every transform carrying one of the job's tags (see "Transform jobs").
 
 If you really must round-trip, project to the writable subset:
 
@@ -153,13 +145,11 @@ mb transform get <id> --full --profile <name> --json \
 
 ## Iterating on a failing transform
 
-When `transform run` fails and you want to retry with a fixed body, **prefer `transform update <id> --file body.json` over `transform delete <id>` + `transform create`.** Update keeps the same row, the same `entity_id`, the same materialized table, and the same on-disk YAML filename:
+When `transform run` fails and you want to retry with a fixed body, **prefer `transform update <id> --file body.json` over `transform delete <id>` + `transform create`.** Update keeps the same row, `entity_id`, materialized table, and on-disk YAML filename:
 
 - `git-sync export` produces **one** clean commit containing only the fix, instead of "broken transform" + "remove broken transform" landing as two commits in `git log`.
-- You don't have to chase `_2` suffixes minted when two YAMLs share a `name` on disk (see the `transform create` notes above).
-- The materialized output table either updates in place or, if the SELECT shape changed incompatibly, errors loudly on the next run rather than landing in a parallel `..._2` table the agent has to clean up. (`transform delete-table <id>` resets the column shape if you need a clean slate.)
-
-Recipe:
+- You don't chase `_2` suffixes minted when two YAMLs share a `name` on disk.
+- The materialized output table either updates in place or, if the SELECT shape changed incompatibly, errors loudly on the next run rather than landing in a parallel `..._2` table you have to clean up. (`transform delete-table <id>` resets the column shape for a clean slate.)
 
 ```bash
 # 1. Try once
@@ -172,7 +162,7 @@ cat > ./.scratch/source.sql <<'SQL'
 <fixed SQL, formatted>
 SQL
 jq -n --rawfile q ./.scratch/source.sql \
-  '{ source: { type: "query", query: { type: "native", database: <db-id>, native: { query: $q } } } }' \
+  '{ source: { type: "query", query: { "lib/type": "mbql/query", database: <db-id>, stages: [{ "lib/type": "mbql.stage/native", native: $q }] } } }' \
   > ./.scratch/source-patch.json
 mb transform update "$ID" --file ./.scratch/source-patch.json --profile <n> --json
 
@@ -180,7 +170,7 @@ mb transform update "$ID" --file ./.scratch/source-patch.json --profile <n> --js
 mb transform run "$ID" --wait --profile <n> --json     # → succeeded
 ```
 
-If you really must `create + delete` instead, do the `delete` **before** the first `git-sync export` so the failed entity never lands in git history. Order matters: agents reflex to "export to checkpoint progress," but for transforms an export of a soft-failed state is mostly noise that needs a follow-up cleanup commit. See the `git-sync` skill, "Read state before mutating" for the ordering rule.
+If you really must `create + delete` instead, do the `delete` **before** the first `git-sync export` so the failed entity never lands in git history — an export of a soft-failed state is noise that needs a follow-up cleanup commit. See `git-sync`, "Read state before mutating", for the ordering rule.
 
 ## Drop the materialized table (keep the transform)
 
@@ -188,7 +178,7 @@ If you really must `create + delete` instead, do the `delete` **before** the fir
 mb transform delete-table <id> --yes --profile <name>
 ```
 
-Useful when you've changed the SELECT and want a fresh `CREATE TABLE` on the next run. **`--yes` is required** in non-interactive contexts; without it the command exits with `--yes required to delete non-interactively`.
+Useful when you've changed the SELECT and want a fresh `CREATE TABLE` on the next run. **`--yes` is required** non-interactively; without it the command exits with `refusing to delete <id> without confirmation — pass --yes to proceed non-interactively`.
 
 ## Delete the transform
 
@@ -196,7 +186,7 @@ Useful when you've changed the SELECT and want a fresh `CREATE TABLE` on the nex
 mb transform delete <id> --yes --profile <name>
 ```
 
-Removes the definition. Whether the materialized table is dropped depends on the server — check with `mb table list --db-id <db-id> --profile <name> --json` if it matters. Same `--yes` rule as `delete-table`.
+Removes the definition. Whether the materialized table is dropped depends on the server — check with `mb table list --db-id <db-id> --profile <name> --json` if it matters. Same `--yes` rule and message as `delete-table`.
 
 ## Transform jobs (schedules)
 
@@ -212,9 +202,3 @@ mb transform-job set-active false --profile <name> --json  # disable every job a
 ```
 
 `transform-job run` is fire-and-forget — the server returns `{message, job_run_id}` immediately, with no per-job-run polling (no `--wait`). Most ad-hoc agent work is one-off `transform run`, not job authoring.
-
-## Don't (transform-specific)
-
-- Don't put `transform run` calls in tight polling loops — pass `--wait` and let the CLI handle the polling. Manual loops without `--wait` will hammer the server.
-- Don't author MBQL 4 (the legacy nested `{ type: "query", query: {...} }` shape) by hand — pull a sample with `mb transform get <id> --full --json`. MBQL 5 (`lib/type: "mbql/query"`) **is** authorable by hand thanks to the `mb query --print-schema` + `--dry-run` feedback loop; for non-trivial pipelines you may still prefer building in the UI and exporting.
-- Don't paste a `transform get` body into `transform update` — the PUT endpoint only accepts writable keys, and unknown keys (notably `tags`, `source_type`, `entity_id`, `created_at`, `last_run`) leak as raw SQL errors. See "Update body: send only writable keys" above. Use `tag_ids` (not `tags`) on the REST contract.

package/skill-data/visualization/SKILL.md

@@ -1,21 +1,21 @@
 ---
 name: visualization
-description: Pick the right `display` (chart type) for a card's data and author its `visualization_settings` via the `mb` CLI. Covers which chart fits which data shape, the required and optional settings per chart type, the rule that settings reference OUTPUT columns by name, minimum-viable settings per chart family, and the `column_settings` JSON-string-key footgun. The full per-chart key catalog lives in references. Load whenever choosing or shaping how a card renders — "what chart should I use for this", "create a bar chart", "make this a line chart", "turn this into a pie", "map this by state", "format this column as currency", "set the pie dimension and metric", "the card renders as a table instead of a chart", "add conditional formatting", or any `display` / `visualization_settings` work.
+description: Choose a card's `display` (chart type) and author its `visualization_settings` for the `mb` CLI — which chart fits which data shape, the required keys per chart, the rule that settings name OUTPUT columns, and the `column_settings` JSON-string-key footgun; the full per-chart key catalog is in references. Use when deciding or fixing how a card renders — "what chart should I use", "make this a bar/line/pie chart", "map this by state", "format this column as currency", "add conditional formatting", "the card renders as a table instead of a chart", or any `display` / `visualization_settings` work.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
 # Visualization: pick the chart, then set it
 
-> **Shared contract (read first).** This skill is part of the `robot-data-engineer` family and follows its shared rules: audience is a non-technical user, so no database jargon (skip "normalize"/"grain"; ERD/foreign key are fine; explain "wide"/"long" the first time you use them). Ask before showing PII row-by-row (names, emails, phones) — default to aggregates. When asked for something the CLI can't do (alerts, dashboard filters), name the limit instead of erroring into raw SQL. Honor the autonomy mode the user picked. Full text and the autonomy slider live in the router — run `mb skills get robot-data-engineer` and read its **Shared Contract** if you haven't.
+> **Building charts as part of a guided data project?** Follow the `data-workflow` **Shared Contract** — answer-first with detail on demand, ask before showing PII, honor the autonomy mode, name what the CLI can't do instead of erroring into raw SQL: `mb skills get data-workflow`.
 
 A card has two presentation fields alongside its `dataset_query`:
 
-- **`display`** — the chart type (`bar`, `line`, `pie`, `scalar`, `map`, `table`, …). One closed set; pick from the enum below.
+- **`display`** — the chart type (`bar`, `line`, `pie`, `scalar`, `map`, `table`, …); pick from the valid values below.
 - **`visualization_settings`** — a map whose keys are **namespaced by `display`** (`graph.*` for bar/line/area/combo, `pie.*` for pie, `table.*` for table, …). The server stores almost anything and **silently ignores keys that don't apply** to the chosen `display`.
 
 Nothing validates `visualization_settings` — there is no pre-flight to fail past. A `display` typo or a misnamed key is accepted by the API; the card just renders as a default table or drops the setting. So **the feedback loop is read-back, not pre-flight**: after `card create`/`update`, confirm with `mb card get <id> --full --json` (or open the card) that it rendered as intended.
 
-Flag conventions and body-input precedence live in the `core` skill (`mb skills get core`); the `dataset_query` itself is the `mbql` skill's job (`mb skills get mbql`). This skill is only about how the result is displayed.
+Flag conventions and body-input precedence live in `core` (`mb skills get core`); the `dataset_query` itself is the `mbql` skill's job (`mb skills get mbql`). This skill is only about how the result is displayed.
 
 Two steps: **(1) pick the `display` that fits the data**, then **(2) bind the data columns and set options**.
 
@@ -27,7 +27,7 @@ Decide which relationship in the data matters most, then pick the chart. The sha
 - **Compare a measure across categories** → `bar` (vertical). Use `row` (horizontal bar) when labels are long or there are many categories. Sort by value unless the dimension has a natural order.
 - **Change over time / trend** → `line` for a continuous series; `bar`/`area` for a few discrete periods. Two measures on unlike scales → `combo` (line + bar, dual-axis) — only when the metrics are genuinely related.
 - **Part-to-whole, one snapshot** → `pie`, but only for a meaningful whole with **≤5 slices**; beyond that use a sorted `bar`/`row`. Composition over time → stacked `area`/`bar`.
-- **Distribution / spread / outliers** → `boxplot` (especially comparing several groups).
+- **Distribution / spread / outliers** → a `bar` histogram (bin the measure — see `mbql` binning); on **v59+** servers `boxplot` compares several groups' spread directly.
 - **Correlation between two measures** → `scatter` (a third measure → bubble size).
 - **Sequential additive contributions** (start → +/− steps → total) → `waterfall`.
 - **Stage drop-off in an ordered, cumulative funnel** → `funnel`.
@@ -35,7 +35,7 @@ Decide which relationship in the data matters most, then pick the chart. The sha
 - **Geographic** → `map`: region/choropleth (a region dimension + a measure), pin (lat + long), or grid/heat (coordinates + measure).
 - **Precise values, many columns, mixed types, or no chart fits** → `table`; `pivot` for a cross-tab of two dimensions; `object` for a single record's detail.
 
-Closed `display` enum (card-level, non-hidden): `table`, `bar`, `line`, `area`, `row`, `pie`, `scalar`, `smartscalar`, `combo`, `pivot`, `funnel`, `map`, `scatter`, `waterfall`, `progress`, `gauge`, `object`, `sankey`, `boxplot`. (`scalar` **is** the "Number" viz — `display: number` is a legacy serialization alias, not a registered visualization; use `scalar`. `list` exists but is hidden — don't pick it. `heading`/`text`/`link`/`iframe`/`action` are dashcard virtuals, not standalone cards — see references.) An unknown `display` is accepted by the API but renders nothing — typos like `bargraph`/`linechart` are the most common "why is my chart blank" cause.
+Valid `display` values — the registered visualizations: `table`, `bar`, `line`, `area`, `row`, `pie`, `scalar`, `smartscalar`, `combo`, `pivot`, `funnel`, `map`, `scatter`, `waterfall`, `progress`, `gauge`, `object`, `sankey`. The API types `display` as a plain string and accepts any value — it renders an unknown one as nothing. (`boxplot` is registered only on **v59+** servers — older ones render it blank; use a `bar` histogram for distributions instead. `scalar` **is** the "Number" viz — `display: number` is a legacy serialization alias, not a registered visualization; use `scalar`. `list` exists but is hidden — don't pick it. `heading`/`text`/`link`/`iframe`/`action` are dashcard virtuals, not standalone cards — see references.) A typo like `bargraph`/`linechart` is accepted and renders blank — the most common "why is my chart blank" cause.
 
 ## Step 2 — bind data columns and set options
 
@@ -53,7 +53,7 @@ Closed `display` enum (card-level, non-hidden): `table`, `bar`, `line`, `area`,
 | `row`                       | as bar; prefer for long/many category labels              | `graph.dimensions`, `graph.metrics`                        |
 | `scatter`                   | two numeric measures (correlation)                        | `graph.dimensions`, `graph.metrics` (`scatter.bubble` opt) |
 | `waterfall`                 | exactly 1 dimension + ≥1 measure; sequential              | `graph.dimensions` (1), `graph.metrics` (1)                |
-| `boxplot`                   | ≥3 cols, ≥2 dimensions, ≥1 measure                        | `graph.dimensions`, `graph.metrics`                        |
+| `boxplot` _(v59+)_          | ≥3 cols, ≥2 dimensions, ≥1 measure                        | `graph.dimensions`, `graph.metrics`                        |
 | `pie`                       | ≥2 rows, ≥2 cols, ≥1 dimension + ≥1 measure; ≤~5 slices   | `pie.dimension`, `pie.metric`                              |
 | `funnel`                    | 2 columns (stage + value); ordered stages                 | `funnel.dimension`, `funnel.metric`                        |
 | `map` (region)              | a string/region dimension + a measure                     | `map.region`, `map.dimension`, `map.metric`                |
@@ -151,7 +151,7 @@ mb skills path visualization           # → the skill dir; then Read references
 
 ## Don't
 
-- Don't invent `display` values (`bargraph`, `linechart`, `histogram`) or use `number`/`list` — use the closed non-hidden enum; the API accepts a typo and renders nothing.
+- Don't invent `display` values (`bargraph`, `linechart`, `histogram`) or use `number`/`list` — use a registered value; the API accepts a typo and renders nothing.
 - Don't put numeric field ids in `graph.dimensions`/`pie.metric`/`scalar.field`/`map.latitude_column` etc. — they take **output column-name strings**.
 - Don't reach for a `pie` with >5 slices, a `combo` of unrelated metrics, or a `pie`/`scalar` to show a trend — see Step 1.
 - Don't write a `column_settings` key as an object — it's a JSON **string** (`"[\"name\",\"COL\"]"`), inner quotes escaped.

package/skill-data/visualization/references/settings.md

@@ -1,5 +1,17 @@
 # visualization_settings — per-chart key reference
 
+## Contents
+
+- [Cartesian — `bar`, `line`, `area`, `combo`, `scatter`, `waterfall`, `row`, `boxplot`](#cartesian--bar-line-area-combo-scatter-waterfall-row-boxplot) — shared keys (binding, stacking, goal/trend, data labels, axes, tooltip) plus `scatter`, `waterfall`, `row`, `boxplot` extras
+- [Part-to-whole & single value — `pie`, `funnel`, `gauge`, `progress`, `scalar`, `smartscalar`](#part-to-whole--single-value--pie-funnel-gauge-progress-scalar-smartscalar)
+- [Tabular, geographic & flow — `table`, `pivot`, `object`, `map`, `sankey`](#tabular-geographic--flow--table-pivot-object-map-sankey) — includes `table.column_formatting` conditional formatting
+- [`column_settings` — per-column formatting](#column_settings--per-column-formatting) — number/date/currency, `view_as`, alignment, mini bars
+- [`series_settings` — per-series styling (cartesian)](#series_settings--per-series-styling-cartesian)
+- [Virtual cards (dashcards only, `card_id: null`)](#virtual-cards-dashcards-only-card_id-null) — heading/text/link/iframe
+- [Click behavior (dashcards only)](#click-behavior-dashcards-only)
+
+---
+
 Authorable keys per `display`, plus the data shape each chart suits and the minimum needed to render. Set keys only to override defaults — an empty `{}` works for a simple aggregate.
 
 All column-naming keys (`graph.dimensions`, `pie.dimension`, `table.columns[].name`, `map.latitude_column`, …) take **output column-name strings** — the names the query produces. Every key and value below is identical in the API form (`mb card create`) and the portable git-sync form, with two exceptions: `column_settings` `["ref", …]` keys and click-behavior dimension targets carry a numeric field id in the API form and a name-path in the portable form. In a JSON body, `column_settings` keys are escaped strings: `"[\"name\",\"TOTAL\"]"`.
@@ -92,6 +104,8 @@ Horizontal bars — use when category labels are long or numerous. Here `graph.d
 
 ## boxplot
 
+_Registered only on **v59+** servers — older ones render `display: boxplot` blank; use a `bar` histogram there._
+
 Use for distribution/spread/outliers, especially across several groups. Needs **unaggregated** rows. **Use for:** ≥3 columns, ≥2 dimensions, ≥1 measure. **Required:** `graph.dimensions`, `graph.metrics`. X-scale is `"ordinal"`.
 
 | Key                        | Type    | Values                                         | Default      |

package/skills/metabase-cli/SKILL.md

@@ -20,8 +20,8 @@ mb skills get core    # auth, flag conventions, every command group
 mb skills list        # everything available on the installed version
 ```
 
-**Doing a whole job, not one command?** If the user wants an outcome — "make sense of my data", "build a data model", "go from raw data to a dashboard", "answer questions about my data", "be my data analyst", "set up analytics for X" — load the front-door router instead and let it drive:
+**Doing a whole job, not one command?** If the user wants an outcome — "make sense of my data", "build a data model", "go from raw data to a dashboard", "answer questions about my data", "be my data analyst", "set up analytics for X" — load the guided end-to-end skill instead and let it drive:
 
 ```bash
-mb skills get robot-data-engineer
+mb skills get data-workflow
 ```

package/dist/add-collection-BqfYL4FU.mjs

@@ -1,10 +0,0 @@
-import "./command-augment-CAur0XOQ.mjs";
-import "./error-CIObEXLY.mjs";
-import "./runtime-CmAIahm5.mjs";
-import "./capabilities-BX1rnVuH.mjs";
-import "./parse-id-B5adfBlS.mjs";
-import "./poll-AduuU55-.mjs";
-import "./poll-task-B00Qwd87.mjs";
-import { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView } from "./add-collection-H4LcP-9B.mjs";
-
-export { add_collection_default as default };

package/dist/auth-BaCMFLTA.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/auth/index.ts
-var auth_default = defineCommand({
-	meta: {
-		name: "auth",
-		description: "Authenticate against a Metabase instance"
-	},
-	default: "login",
-	subCommands: {
-		login: () => import("./login-C0Rf2hg0.mjs").then((m) => m.default),
-		status: () => import("./status-DY92F9mn.mjs").then((m) => m.default),
-		list: () => import("./list-FR8Q1SzV.mjs").then((m) => m.default),
-		logout: () => import("./logout-C7_UON-s.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { auth_default as default };

package/dist/card-DzH3aK0a.mjs

@@ -1,20 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/card/index.ts
-var card_default = defineCommand({
-	meta: {
-		name: "card",
-		description: "Manage Metabase cards (questions, models, metrics)"
-	},
-	subCommands: {
-		list: () => import("./list-D52_BozQ.mjs").then((mod) => mod.default),
-		get: () => import("./get-CXMv-r1p.mjs").then((mod) => mod.default),
-		query: () => import("./query-BUkuB4bZ.mjs").then((mod) => mod.default),
-		create: () => import("./create-B-mvVFIl.mjs").then((mod) => mod.default),
-		update: () => import("./update-I3TA2Tem.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-BCXoM1nX.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { card_default as default };

package/dist/collection-Wagz-ira.mjs

@@ -1,20 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/collection/index.ts
-var collection_default = defineCommand({
-	meta: {
-		name: "collection",
-		description: "Manage Metabase collections"
-	},
-	subCommands: {
-		list: () => import("./list-F0vkE22V.mjs").then((mod) => mod.default),
-		get: () => import("./get-rFcAVIch.mjs").then((mod) => mod.default),
-		items: () => import("./items-1KkBMiO4.mjs").then((mod) => mod.default),
-		tree: () => import("./tree-B3f5F_dP.mjs").then((mod) => mod.default),
-		create: () => import("./create-CF2Zn4pT.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-hN8PfvhX.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { collection_default as default };

package/dist/dashboard-OUgS1Gi-.mjs

@@ -1,21 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/dashboard/index.ts
-var dashboard_default = defineCommand({
-	meta: {
-		name: "dashboard",
-		description: "Manage Metabase dashboards"
-	},
-	subCommands: {
-		list: () => import("./list-C4KnM3Rq.mjs").then((mod) => mod.default),
-		get: () => import("./get-Nc5GOs6-.mjs").then((mod) => mod.default),
-		cards: () => import("./cards-Bw37jizL.mjs").then((mod) => mod.default),
-		create: () => import("./create-DSWjS09p.mjs").then((mod) => mod.default),
-		update: () => import("./update-DOfL_KPx.mjs").then((mod) => mod.default),
-		"update-dashcard": () => import("./update-dashcard-BXZ4vS15.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-C6MDtV1F.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { dashboard_default as default };