@metabase/cli 0.1.5 → 0.1.7

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

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 Metabase content (cards, dashboards, transforms, snippets, collections, …) can live in a git repo as YAML and round-trip in and out of a Metabase instance via the `git-sync` verbs. The instance is configured with a `remote-sync-*` settings block (URL, branch, token, type read-only/read-write); the CLI drives the sync tasks against `/api/ee/remote-sync/*`.
 
-This skill covers the import/export workflow. The general flag conventions and auth setup live in the `core` skill (`mb skills get core`). To author content YAML by hand, also load the `metabase-representation-format` skill — it covers the file-tree layout and per-resource YAML shape.
+This skill covers the import/export workflow. The general flag conventions and auth setup live in the `core` skill (`mb skills get core`). To author content YAML by hand: the per-resource clause and settings shapes mirror the API form — query bodies follow the `mbql` skill, `visualization_settings` follow the `viz` skill — except the portable YAML uses **name-based** references (e.g. `[Sample Database, PUBLIC, ORDERS, TOTAL]`, and entity-ids for cross-entity FKs) where the API form uses numeric ids. For the on-disk folder layout, model new files on what the synced repo already contains.
 
 ## Adding / removing a directory (collection) to sync
 

package/skill-data/mbql/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: mbql
+description: Author Metabase MBQL 5 query bodies for the `mb` CLI — the only hand-authorable query format. Covers the JSON shape (lib/type mbql/query, flat stages, numeric ids), the "options object always second" clause rule, lib/uuid minting, the print-schema → dry-run → run validation loop, where MBQL 5 is consumed (mb query, card dataset_query, transform source.query, measure/segment definition), the flat-vs-legacy-envelope footgun, and naming aggregation output columns. Load whenever building or fixing an MBQL query by hand — "write an MBQL query", "create a card from MBQL", "the dataset_query is wrong", "fix the validation errors", "aggregate and group by", "order by the count", or any `--dry-run` / `mb query` work.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# MBQL 5
+
+MBQL 5 is the **only query format you can author by hand** with confidence — it has a bundled JSON Schema, so the CLI pre-flight-validates it before sending. Legacy MBQL 4 and native SQL are accepted but **not** schema-validated (see "Other formats" below).
+
+Prefer MBQL over native SQL: MBQL is portable across warehouse engines and the CLI can validate it. Reach for native only when the query needs something MBQL can't express.
+
+The general flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`).
+
+## The shape
+
+A query is a flat object — `lib/type`, a numeric `database` id, and an ordered `stages` array. No recursive `source-query` nesting; multi-step queries are sibling stages.
+
+```json
+{
+  "lib/type": "mbql/query",
+  "database": 1,
+  "stages": [
+    {
+      "lib/type": "mbql.stage/mbql",
+      "source-table": 7,
+      "aggregation": [["count", { "lib/uuid": "<mint via mb uuid>" }]],
+      "breakout": [["field", { "temporal-unit": "month", "lib/uuid": "<mint>" }, 22]]
+    }
+  ]
+}
+```
+
+- **Numeric ids only.** `database`, `source-table`, and field ids are integers from `mb database list` / `mb table get <id> --include fields`. (The portable YAML representation under git-sync uses _names_ like `[Sample Database, PUBLIC, ORDERS]`; the CLI's `/api/dataset` form uses numeric ids — don't mix them.)
+- **First stage** carries `source-table` (a table id) or `source-card` (a saved card). Later stages omit both and read the previous stage's output columns by name.
+- `source-card` references a saved card by entity id; downstream fields are referenced by column name (string), not a field id.
+
+## The one rule that trips everyone: options object is **second**
+
+Every clause is `[op, {options}, ...args]`. The options object is element **1**, args follow.
+
+```json
+["field", { "base-type": "type/Text", "lib/uuid": "<mint>" }, 1779]   // field id is THIRD
+["count", { "lib/uuid": "<mint>" }]                                    // no args
+["sum",   { "lib/uuid": "<mint>" }, ["field", { "lib/uuid": "<mint>" }, 42]]
+["=",     { "lib/uuid": "<mint>" }, ["field", { "lib/uuid": "<mint>" }, 1779], "delivered"]
+["asc",   { "lib/uuid": "<mint>" }, ["field", { "lib/uuid": "<mint>" }, 42]]
+```
+
+The legacy MBQL 4 field shape `["field", id, opts]` (id second) is **rejected** here. A slot-1 violation surfaces from `--dry-run` as `must be the field options object` / `must be the clause options object` at `/stages/0/<verb>/<n>/1`.
+
+The same `[op, {options}, …]` rule holds for `aggregation`, `breakout` (a list of field refs), `filters` (implicitly ANDed; nest an explicit `["or", {}, …]` for OR), `order-by`, `expressions`, and join `conditions`.
+
+## UUIDs: mint them, never invent them
+
+Every clause options object carries a `lib/uuid` (UUID v4). The schema enforces RFC 4122 strictly, so placeholders (`"a1"`, `"uuid-1"`, `"agg-uuid-001"`) fail pre-flight with `must be a UUID v4 (RFC 4122) — run \`mb uuid\` …`. The same applies to native template-tag ids and any other `format: "uuid"` slot.
+
+```bash
+mb uuid --count 5 --json     # → ["…","…","…","…","…"] — mint exactly what you need, in one call
+```
+
+Workflow: count the slots (one per clause options object), `mb uuid --count <N> --json`, substitute each minted value as you build the JSON. Never copy a UUID from docs, a prior query, or another session.
+
+**Aggregation/expression refs are the only legitimate reuse.** To reference an aggregation downstream (in `order-by` or a later stage), use `["aggregation", {options}, "<uuid>"]` where the third arg is the **string** `lib/uuid` of the target aggregation — the same minted value, by string equality. A numeric position fails with `must be the target aggregation's lib/uuid (string), not a numeric position`. Expression refs work the same way but key off the expression's name string.
+
+```json
+"aggregation": [["count", { "lib/uuid": "AGG_UUID" }]],
+"order-by":   [["desc", { "lib/uuid": "ORDER_UUID" },
+                 ["aggregation", { "lib/uuid": "REF_UUID" }, "AGG_UUID"]]]
+```
+
+(`AGG_UUID` appears twice and must be the _same_ minted value; `ORDER_UUID` and `REF_UUID` are distinct.)
+
+## Authoring loop: print-schema → dry-run → run
+
+`mb query` is the canonical authoring surface. Three modes:
+
+```bash
+mb query --print-schema --profile <n> > /tmp/mbql-schema.json   # 1. fetch the schema
+mb query --file q.json --dry-run --profile <n>                  # 2. validate, no network
+mb query --file q.json --profile <n> --json                     # 3. validate + run
+```
+
+- `--print-schema` emits `{ schema, defs }` where `defs` carries `id.yaml` / `parameter.yaml` / `ref.yaml` / `temporal_bucketing.yaml` keyed by the path used in the schema's `$ref`s. Read it first for any non-trivial query — cheaper than guess-and-fail.
+- `--dry-run` validates and emits `{ ok, errors: [{ path, message }] }`. Exit `0` valid, `2` invalid. No request sent. Iterate until `ok: true`.
+- run (no flag) validates, then on success sends to `/api/dataset`. On validation failure it writes the same envelope, exits `2`, and **never sends**.
+
+`path` is a JSON Pointer into the body (`/stages/0/aggregation/0`); `message` is the validator error. Exit codes: `0` valid + ran, `2` validation failed / malformed body, `1` server-side error after a valid pre-flight.
+
+`--skip-validate` bypasses the pre-flight and sends as-is — use only when the bundled schema disagrees with what the server actually accepts (drift / false negative). Mutually exclusive with `--dry-run`. The same flag exists on `card create/update` and `transform create/update`.
+
+## Where MBQL 5 is consumed
+
+The same body and the same pre-flight apply everywhere a query is embedded. Each pre-flights only when the value is MBQL 5 (`lib/type: "mbql/query"`); legacy shapes skip it; `--skip-validate` bypasses.
+
+| Command                                 | MBQL 5 lives at                                | Notes                                       |
+| --------------------------------------- | ---------------------------------------------- | ------------------------------------------- |
+| `mb query`                              | the whole body                                 | ad-hoc run against `/api/dataset`           |
+| `card create` / `card update`           | `dataset_query`                                | a **flat** `mbql/query` — see footgun below |
+| `transform create` / `transform update` | `source.query` (when `source.type` is `query`) | materializes to a warehouse table           |
+| `measure create` / `measure update`     | `definition`                                   | exactly one `aggregation`, no `filters`     |
+| `segment create` / `segment update`     | `definition`                                   | filter macro tied to a table                |
+
+## Footgun: `dataset_query` is the flat mbql/query, not a legacy envelope
+
+The most common mistake. The legacy MBQL 4 shape `{ "type": "query", "database": N, "query": {…} }` looks similar but is wrong for MBQL 5. `dataset_query` (and `source.query`, and `definition`) **is the `mbql/query` value itself**:
+
+```json
+"dataset_query": {
+  "lib/type": "mbql/query",
+  "database": 2,
+  "stages": [{ "lib/type": "mbql.stage/mbql", "source-table": 190,
+               "aggregation": [["count", { "lib/uuid": "<mint>" }]] }]
+}
+```
+
+No `type:"query"` wrapper, no `query:` nesting. If you wrap MBQL 5 inside a legacy envelope the CLI rejects it pre-send with a `ConfigError` (no `--skip-validate` gets it past). If it ever reached the server it would store silently and fail at run time with `Initial MBQL stage must have either :source-table or :source-card`.
+
+## Other formats skip pre-flight
+
+Anything that is not `lib/type: "mbql/query"` is sent as-is and normalized server-side:
+
+- **Legacy MBQL 4** — `{ "type": "query", "database": N, "query": { "source-table": T, … } }`
+- **Native SQL** — `{ "type": "native", "database": N, "native": { "query": "SELECT …" } }`
+
+`mb query --file probe.json` runs these directly; `--dry-run` on them returns `{ ok: true, errors: [] }`. Don't author MBQL 4 by hand — if you need a legacy or complex query, build it in the Metabase UI and pull the body with `mb card get <id> --full --json` / `mb transform get <id> --full --json`.
+
+## Naming aggregation output columns
+
+Default MBQL 5 aggregations materialize as `count`, `count_where`, `avg`, `avg_2`, `sum`, … — fine for an ad-hoc run, ugly when the output is a transform target table or a card column. Set `name` (becomes the warehouse column name) and `display-name` (the UI header) in the aggregation's options:
+
+```json
+[
+  "count",
+  { "lib/uuid": "<mint>", "name": "shipments_shipped", "display-name": "Shipments shipped" }
+]
+```
+
+## Operator reference
+
+The full operator vocabulary — filter operators (`=`, `!=`, `<`, `between`, `contains`, `is-null`, …), aggregation functions (`count`, `sum`, `avg`, `distinct`, `count-where`, `share`, …), expression operators (arithmetic, string, temporal), temporal-bucketing units, and binning strategies — lives in this skill's `references/operators.md`, in the CLI's numeric-id form. Load it on demand rather than dumping the schema:
+
+```bash
+mb skills get mbql --full     # appends references/operators.md to this body
+mb skills path mbql           # → the skill dir; then Read references/operators.md
+```
+
+`mb query --print-schema` is the exhaustive-but-heavy fallback (the full JSON Schema, ~1600 lines). The cheat-sheet covers the vocabulary; the `--dry-run` loop settles any disagreement.
+
+## Don't
+
+- Don't invent, hard-code, or copy `lib/uuid` values — `mb uuid` every slot at author time.
+- Don't put the options object anywhere but slot 1, and don't use the legacy `["field", id, opts]` order.
+- Don't wrap an MBQL 5 body in `{type:"query", query:…}` — `dataset_query` / `source.query` / `definition` is the flat `mbql/query`.
+- Don't author MBQL 4 by hand — build it in the UI and pull it with `… get <id> --full --json`.
+- Don't skip the `--dry-run` loop on a non-trivial query — it's free and exact.

package/skill-data/mbql/references/operators.md

@@ -0,0 +1,253 @@
+# MBQL 5 operator reference
+
+The complete clause vocabulary the bundled schema accepts, in the CLI's API/numeric
+form. The clause _structure_ and the slot-1-options rule are in the SKILL.md body —
+this file is the catalog of which operators exist and their arguments.
+
+**Reading the tables.** Every clause is `[op, {options}, ...args]`. Below, `{…}`
+abbreviates the slot-1 options object, which always carries `lib/uuid` (mint with
+`mb uuid`) plus any operator-specific option noted in the row. Field refs are numeric:
+`["field", {…}, <field-id>]`. Everything here passes `mb query --dry-run`; when in
+doubt, that loop is the authority.
+
+> Relative date filters use **`time-interval`** / **`relative-time-interval`** (below),
+> not bare date literals. If you pulled a query from the UI that contains
+> `relative-datetime` or `absolute-datetime`, the bundled schema does not yet model
+> those — send it with `--skip-validate` rather than rewriting it.
+
+---
+
+## Filter operators
+
+A stage's `filters` is a list of boolean clauses, implicitly ANDed. Nest an explicit
+`["or", {…}, …]` for OR.
+
+### Logical
+
+| Op    | Args               | Notes                                                 |
+| ----- | ------------------ | ----------------------------------------------------- |
+| `and` | 2+ boolean clauses | Logical AND (usually implicit via the `filters` list) |
+| `or`  | 2+ boolean clauses | Logical OR                                            |
+| `not` | 1 boolean clause   | Logical NOT                                           |
+
+### Comparison
+
+| Op                | Args                                                     | Notes                   |
+| ----------------- | -------------------------------------------------------- | ----------------------- |
+| `=`               | field, 1+ values                                         | Multi-value = IN        |
+| `!=`              | field, 1+ values                                         | Multi-value = NOT IN    |
+| `<` `>` `<=` `>=` | 2 orderable                                              |                         |
+| `between`         | field, min, max                                          | Inclusive               |
+| `inside`          | lat-field, lon-field, lat-max, lon-min, lat-min, lon-max | Geographic bounding box |
+
+```json
+["between", {…}, ["field", {…}, 12], 10, 100]
+["=", {…}, ["field", {…}, 7], "Widget", "Gadget"]
+```
+
+### Null / empty
+
+| Op          | Args                | Notes                 |
+| ----------- | ------------------- | --------------------- |
+| `is-null`   | 1 expression        |                       |
+| `not-null`  | 1 expression        |                       |
+| `is-empty`  | 1 string expression | NULL or `""`          |
+| `not-empty` | 1 string expression | not NULL and not `""` |
+
+### String match
+
+N-ary (multiple values OR'd). Accept a `case-sensitive` option (default `true`) in the
+options object.
+
+| Op                 | Args              |
+| ------------------ | ----------------- |
+| `contains`         | field, 1+ strings |
+| `does-not-contain` | field, 1+ strings |
+| `starts-with`      | field, 1+ strings |
+| `ends-with`        | field, 1+ strings |
+
+```json
+["contains", { "lib/uuid": "<mint>", "case-sensitive": false }, ["field", {…}, 9], "widget"]
+```
+
+### Temporal
+
+| Op                       | Args                                                       | Notes                                               |
+| ------------------------ | ---------------------------------------------------------- | --------------------------------------------------- |
+| `time-interval`          | temporal-field, n, unit                                    | `n` = integer, or `"current"` / `"last"` / `"next"` |
+| `relative-time-interval` | temporal-field, value, bucket, offset-value, offset-bucket | interval with offset                                |
+
+Units (truncation only): `millisecond`, `second`, `minute`, `hour`, `day`, `week`,
+`month`, `quarter`, `year`.
+
+```json
+["time-interval", {…}, ["field", {…}, 22], -30, "day"]      // last 30 days
+["time-interval", {…}, ["field", {…}, 22], "current", "month"]
+```
+
+### Segment
+
+| Op        | Args       | Notes                     |
+| --------- | ---------- | ------------------------- |
+| `segment` | segment id | Reference a saved segment |
+
+---
+
+## Aggregation functions
+
+A stage's `aggregation` is a list of aggregation clauses.
+
+| Op                      | Args                       | Notes                            |
+| ----------------------- | -------------------------- | -------------------------------- |
+| `count`                 | none, or 1 expression      | with arg: count non-NULL         |
+| `sum` `avg` `min` `max` | 1 numeric/orderable        |                                  |
+| `distinct`              | 1 expression               | count of distinct values         |
+| `cum-count`             | none or 1 expression       | running count                    |
+| `cum-sum`               | 1 numeric                  | running sum                      |
+| `stddev` `var` `median` | 1 numeric                  |                                  |
+| `percentile`            | numeric, p (0.0–1.0)       |                                  |
+| `count-where`           | 1 boolean clause           |                                  |
+| `sum-where`             | numeric, boolean clause    |                                  |
+| `distinct-where`        | expression, boolean clause |                                  |
+| `share`                 | 1 boolean clause           | proportion 0–1                   |
+| `metric`                | metric id                  | reference a saved metric card    |
+| `measure`               | measure id                 | reference a saved measure (v59+) |
+
+```json
+["count", {…}]
+["sum", {…}, ["field", {…}, 42]]
+["count-where", {…}, [">", {…}, ["field", {…}, 42], 100]]
+```
+
+**Naming** — set `name` (warehouse column) and/or `display-name` (UI header) in the
+options object: `["sum", { "lib/uuid": "<mint>", "name": "revenue", "display-name": "Revenue" }, …]`.
+
+**Window function** — `offset` is only valid inside `aggregation`:
+
+| Op       | Args          | Notes                                             |
+| -------- | ------------- | ------------------------------------------------- |
+| `offset` | expression, n | value n rows before (negative) / after (positive) |
+
+---
+
+## Expression operators
+
+Used in `expressions` (named, via `lib/expression-name` in options) and inline.
+
+### Arithmetic
+
+| Op  | Args                               | Notes                |
+| --- | ---------------------------------- | -------------------- |
+| `+` | 2+ numeric, or temporal + interval |                      |
+| `-` | 1+ numeric, or temporal − interval | unary = negation     |
+| `*` | 2+ numeric                         |                      |
+| `/` | 2+ numeric                         | always returns float |
+
+### Math
+
+| Op                           | Args           |
+| ---------------------------- | -------------- |
+| `abs` `ceil` `floor` `round` | 1 numeric      |
+| `power`                      | base, exponent |
+| `sqrt` `exp` `log`           | 1 numeric      |
+
+### String
+
+| Op                                 | Args                            |
+| ---------------------------------- | ------------------------------- |
+| `concat`                           | 2+ expressions                  |
+| `substring`                        | str, start (1-indexed), length? |
+| `replace`                          | str, find, replace              |
+| `regex-match-first`                | str, regex                      |
+| `split-part`                       | str, delimiter, position        |
+| `trim` `ltrim` `rtrim`             | 1 string                        |
+| `upper` `lower`                    | 1 string                        |
+| `length`                           | 1 string                        |
+| `host` `domain` `subdomain` `path` | 1 URL string                    |
+
+### Temporal
+
+| Op                                                                                  | Args                            | Notes                      |
+| ----------------------------------------------------------------------------------- | ------------------------------- | -------------------------- |
+| `now`                                                                               | none                            | datetime                   |
+| `today`                                                                             | none                            | date                       |
+| `interval`                                                                          | amount, unit                    | a temporal interval        |
+| `datetime-add`                                                                      | temporal, amount, unit          |                            |
+| `datetime-subtract`                                                                 | temporal, amount, unit          |                            |
+| `datetime-diff`                                                                     | datetime1, datetime2, unit      |                            |
+| `convert-timezone`                                                                  | temporal, target-tz, source-tz? |                            |
+| `get-year` `get-quarter` `get-month` `get-day` `get-hour` `get-minute` `get-second` | 1 temporal                      | integer component          |
+| `get-day-of-week`                                                                   | temporal, mode?                 | mode `iso`/`us`/`instance` |
+| `get-week`                                                                          | temporal, mode?                 | mode `iso`/`us`/`instance` |
+| `temporal-extract`                                                                  | temporal, unit, mode?           | generic extraction         |
+| `month-name` `quarter-name` `day-name`                                              | 1 integer                       | name from number           |
+
+Add/subtract/interval units: `year`, `quarter`, `month`, `week`, `day`, `hour`,
+`minute`, `second`, `millisecond`. `datetime-diff` units: same minus `millisecond`.
+`temporal-extract` units: `year-of-era`, `quarter-of-year`, `month-of-year`,
+`week-of-year-iso`, `week-of-year-us`, `week-of-year-instance`, `day-of-month`,
+`day-of-week`, `day-of-week-iso`, `hour-of-day`, `minute-of-hour`, `second-of-minute`.
+
+### Type conversion
+
+| Op        | Args              |
+| --------- | ----------------- |
+| `integer` | string or numeric |
+| `float`   | string            |
+| `text`    | 1 expression      |
+
+### Conditional
+
+| Op         | Args                           | Notes                                                |
+| ---------- | ------------------------------ | ---------------------------------------------------- |
+| `case`     | `[[cond, value], …]`, default? | if/then/else; default is the trailing positional arg |
+| `if`       | same as `case`                 | alias for `case`                                     |
+| `coalesce` | 2+ expressions                 | first non-null                                       |
+
+```json
+["case", { "lib/uuid": "<mint>", "lib/expression-name": "Tier" },
+  [[[">", {…}, ["field", {…}, 14], 100], "Premium"],
+   [["<=", {…}, ["field", {…}, 14], 20], "Budget"]],
+  "Standard"]
+```
+
+(`case`'s first arg is a list of `[condition, value]` pairs; the optional 4th
+positional arg is the default.)
+
+---
+
+## References (within clauses)
+
+| Ref         | Shape                                | Notes                                                                          |
+| ----------- | ------------------------------------ | ------------------------------------------------------------------------------ |
+| field       | `["field", {…}, <field-id>]`         | numeric id; options may carry `base-type`, `temporal-unit`, `binning`          |
+| expression  | `["expression", {…}, "<name>"]`      | by the expression's `lib/expression-name` string                               |
+| aggregation | `["aggregation", {…}, "<agg-uuid>"]` | 3rd arg is the **string** `lib/uuid` of the target aggregation, not a position |
+
+## Field option: temporal bucketing
+
+`temporal-unit` in a field ref's options buckets a datetime.
+
+- Truncation: `default`, `millisecond`, `second`, `minute`, `hour`, `day`, `week`,
+  `month`, `quarter`, `year`.
+- Extraction (returns an integer): `minute-of-hour`, `hour-of-day`, `day-of-week`,
+  `day-of-week-iso`, `day-of-month`, `day-of-year`, `week-of-year`, `week-of-year-iso`,
+  `month-of-year`, `quarter-of-year`, `year-of-era`, `second-of-minute`.
+
+```json
+["field", { "lib/uuid": "<mint>", "temporal-unit": "month" }, 22]
+```
+
+## Field option: binning
+
+`binning` in a field ref's options groups a numeric/coordinate column.
+
+| `strategy`  | Extra property       | Notes                            |
+| ----------- | -------------------- | -------------------------------- |
+| `num-bins`  | `num-bins` (integer) | fixed number of equal-width bins |
+| `bin-width` | `bin-width` (number) | fixed bin width                  |
+| `default`   | —                    | Metabase chooses                 |
+
+```json
+["field", { "lib/uuid": "<mint>", "binning": { "strategy": "num-bins", "num-bins": 10 } }, 14]
+```

package/skill-data/transform/SKILL.md

@@ -17,47 +17,9 @@ 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 much more verbose; pull a sample with `mb transform get <id> --full --json` if you need its shape.
+Native SQL is the simplest source and the easiest to author by hand (see "Create + run" below). 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.
 
-If `source.query` is **MBQL 5** (`lib/type: "mbql/query"`), `transform create` and `transform update` validate it against the bundled query schema before sending; failure exits 2 with `{ ok, errors: [{path, message}] }` on stdout. To author MBQL 5 by hand: fetch the schema via `mb query --print-schema --profile <n>`, iterate the body with `mb query --file q.json --dry-run --profile <n>` until `ok: true`, then drop it into `source.query`. Legacy MBQL 4 and native sources skip pre-flight. Pass `--skip-validate` to bypass the pre-flight and let the server be the authority — useful when the bundled schema disagrees with what the server actually accepts.
-
-**Mint UUIDs for `lib/uuid` slots before assembling the body — never invent, hard-code, or reuse them.** Every clause options object carries a `lib/uuid` (UUID v4); the bundled schema enforces RFC 4122 format strictly, so placeholder strings fail `--dry-run`. Workflow: count the slots, run `mb uuid --count <N> --json`, substitute each minted value into its slot. The examples below use `<UUID:label>` sentinels (NOT valid UUIDs) so the assembly step is unambiguous — replace each sentinel with a freshly-minted UUID before sending. Same `<UUID:label>` token must be replaced with the same minted UUID (used for aggregation-ref ↔ aggregation pairing); distinct sentinels get distinct UUIDs.
-
-**Clause shape: opts always second, args after.** Every clause is `[op, {options}, ...args]`. Field refs are `["field", {options}, fieldId]` (id third), not the legacy MBQL 4 shape `["field", id, opts]`. The same rule holds for aggregations, filters, order-by — the options object never moves out of slot 1.
-
-## MBQL 5 aggregations: name your output columns
-
-Default MBQL 5 aggregations materialize as `count`, `count_where`, `count_where_2`, `avg`, `avg_2`, `sum`, … — ugly when the result is a transform target. Pass `name` and `display-name` in the aggregation's options object to control them. Mint 4 UUIDs (`mb uuid --count 4 --json`) for the slots below before assembling:
-
-```json
-["count",
- {"lib/uuid": "<UUID:agg-shipped>", "name": "shipments_shipped", "display-name": "Shipments shipped"}]
-
-["count-where",
- {"lib/uuid": "<UUID:agg-delivered>", "name": "shipments_delivered", "display-name": "Shipments delivered"},
- ["=", {"lib/uuid": "<UUID:eq-filter>"},
-  ["field", {"base-type": "type/Text", "lib/uuid": "<UUID:status-field>"}, 1779],
-  "delivered"]]
-```
-
-The `name` value becomes the warehouse column name on the materialized table. The `display-name` is the column header in the UI.
-
-## MBQL 5 order-by referencing an aggregation
-
-Order by an aggregation column with an `["aggregation", {…}, "<aggregation-uuid>"]` ref — the third arg is the **string UUID** of the target aggregation's `lib/uuid`, **not** its numeric position. The aggregation's own `lib/uuid` and the ref's third element must be the same minted UUID (string equality); the order-by clause itself and the ref clause each carry their own separate `lib/uuid` in their options. Mint 3 UUIDs and substitute — note that `<UUID:agg-count>` appears twice and gets the same minted value:
-
-```json
-"aggregation": [
-  ["count", {"lib/uuid": "<UUID:agg-count>"}]
-],
-"order-by": [
-  ["desc", {"lib/uuid": "<UUID:order-desc>"},
-    ["aggregation", {"lib/uuid": "<UUID:agg-ref>"},
-     "<UUID:agg-count>"]]
-]
-```
-
-A numeric index (`["aggregation", {…}, 0]`) fails pre-flight with `must be the target aggregation's lib/uuid (string), not a numeric position` at `/stages/0/order-by/0/2/2`.
+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".
 
 ## Create + run (native SQL)
 

package/skill-data/viz/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: viz
+description: Author Metabase `visualization_settings` and pick the right `display` for cards via the `mb` CLI. Covers the display → settings-namespace map (graph.*, pie.*, funnel.*, scalar.*, table.*, …), the column-name-vs-numeric-field-id rule, the `column_settings` JSON-string-key footgun, worked API-form examples per chart family, and the pull-from-UI escape hatch for complex charts. Load whenever shaping how a card renders by hand — "create a bar chart", "make this a line chart", "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 `visualization_settings` work.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Visualization settings
+
+A card has two presentation fields alongside its `dataset_query`:
+
+- **`display`** — the chart type (`bar`, `line`, `pie`, `scalar`, `table`, …). One closed set of values; pick from the enum below.
+- **`visualization_settings`** — a free-form map whose keys are **namespaced by `display`** (`graph.*` for bar/line, `pie.*` for pie, …). The server stores almost anything and **silently ignores keys that don't apply** to the chosen `display`.
+
+The MBQL pre-flight does **not** validate `visualization_settings` — there is no `--skip-validate` to fail past, because nothing checks it. A `display` typo or a misnamed key is accepted by the API and 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.
+
+The general flag conventions and body-input precedence live in the `core` skill (`mb skills get core`); the `dataset_query` body itself is the `mbql` skill's job (`mb skills get mbql`). This skill is only about how the result is displayed.
+
+## `display` decides everything
+
+`display` selects which setting namespace is read. Pick `display` first, then only the matching namespace's keys matter.
+
+| `display`                                   | Settings namespace(s)                                     | Key columns are named by |
+| ------------------------------------------- | --------------------------------------------------------- | ------------------------ |
+| `bar` `line` `area` `combo` `row` `scatter` | `graph.*`, `series_settings`, `column_settings`           | output column **name**   |
+| `waterfall`                                 | `graph.*` + `waterfall.*`                                 | output column name       |
+| `boxplot`                                   | `graph.*` + `boxplot.*`                                   | output column name       |
+| `pie`                                       | `pie.*`, `column_settings`                                | output column name       |
+| `scalar` `number`                           | `scalar.*`                                                | output column name       |
+| `smartscalar`                               | `scalar.comparisons`                                      | output column name       |
+| `funnel`                                    | `funnel.*`                                                | output column name       |
+| `gauge`                                     | `gauge.*`                                                 | —                        |
+| `map`                                       | `map.*`                                                   | output column name       |
+| `pivot`                                     | `pivot_table.*`, `table.*`                                | output column name       |
+| `sankey`                                    | `sankey.*`                                                | output column name       |
+| `table`                                     | `table.*`, `column_settings`                              | output column name       |
+| `object` `list`                             | `column_settings`                                         | output column name       |
+| `progress`                                  | `progress.goal`, `progress.color` (sparse — pull from UI) | —                        |
+| `heading` `text` `link` `iframe` `action`   | dashcard-only `virtual_card` (see references)             | —                        |
+
+Closed `display` enum (card-level): `table`, `bar`, `line`, `area`, `row`, `pie`, `scalar`, `smartscalar`, `number`, `combo`, `pivot`, `funnel`, `map`, `scatter`, `waterfall`, `progress`, `gauge`, `object`, `list`, `sankey`, `boxplot`. (`heading`/`text`/`link`/`iframe`/`action` are dashcard virtuals, not standalone cards.) An unknown value is accepted by the API but renders nothing useful — typos like `bargraph`/`linechart` are the most common cause of a "why is my chart blank" report.
+
+## The rule that trips everyone: settings name **output columns**, by name
+
+`graph.dimensions`, `graph.metrics`, `pie.dimension`, `pie.metric`, `scalar.field`, `funnel.metric`, `map.latitude_column`, … all take **output column-name strings** — the names the query _produces_, not field ids. A `count` aggregation outputs the column `count`; a breakout on a field outputs that field's name; a named aggregation outputs its `name`. These strings are **identical in the API form and the portable (git-sync) form** — no numeric-vs-name footgun here.
+
+So the names you put in `visualization_settings` come from the query's output, not from `mb field`/`mb table`. If you set `name` on an aggregation (see the `mbql` skill, "Naming aggregation output columns"), use that same string here.
+
+## Minimum-viable settings per chart family (API form)
+
+Each example is the `visualization_settings` block to pair with the given `display` on a `card create`/`update` body. The `dataset_query` is elided — build it per the `mbql` skill. The output columns referenced (`CATEGORY`, `count`) are whatever the query's breakout/aggregation produce.
+
+**Bar / line / area** — one dimension on the x-axis, one or more metrics:
+
+```json
+"display": "bar",
+"visualization_settings": {
+  "graph.dimensions": ["CATEGORY"],
+  "graph.metrics": ["count"]
+}
+```
+
+(Switch `display` to `line` or `area` with the same `graph.*` keys. Multiple metrics: `"graph.metrics": ["count", "sum"]`. Stacked: add `"stackable.stack_type": "stacked"`.)
+
+**Pie** — one dimension, one metric:
+
+```json
+"display": "pie",
+"visualization_settings": { "pie.dimension": "CATEGORY", "pie.metric": "count" }
+```
+
+**Scalar** (single big number) — the field to surface:
+
+```json
+"display": "scalar",
+"visualization_settings": { "scalar.field": "count" }
+```
+
+**Table** — column order/visibility plus per-column formatting:
+
+```json
+"display": "table",
+"visualization_settings": {
+  "table.columns": [
+    { "name": "CATEGORY", "enabled": true },
+    { "name": "count", "enabled": true }
+  ],
+  "column_settings": {
+    "[\"name\",\"count\"]": { "column_title": "Orders" }
+  }
+}
+```
+
+An **empty** `"visualization_settings": {}` is valid for any `display` — Metabase falls back to sensible defaults (it auto-picks dimensions/metrics for a simple aggregate). Set keys only to override the defaults.
+
+## `column_settings`: the JSON-string-key footgun
+
+`column_settings` is a map **whose keys are themselves JSON-encoded arrays** — so inside a JSON body the inner quotes must be escaped. The key is a _string_, never an object.
+
+- **Prefer the name form:** `["name", "<output column name>"]` → in a JSON body, `"[\"name\",\"count\"]"`. This is the canonical key Metabase writes (`getColumnKey`), and it's **identical in API and portable form**. Use it unless you have a reason not to.
+- **Ref form (legacy order!):** `["ref", ["field", <id>, <opts>]]`. The inner field ref here uses the **legacy MBQL-4 order** `["field", id, options]` (id **second**) — _not_ the MBQL-5 order `["field", {options}, id]` you use in `dataset_query`. In the API form `<id>` is the **numeric** field id; the portable form uses a name path. Because the order differs from MBQL 5, this form is easy to get wrong — reach for the name form instead.
+
+```json
+"column_settings": {
+  "[\"name\",\"TOTAL\"]": { "number_style": "currency", "currency": "USD", "decimals": 2 },
+  "[\"name\",\"CREATED_AT\"]": { "date_style": "MMMM D, YYYY" }
+}
+```
+
+The exhaustive per-column key list (number/date/link formatting, `view_as`, click behavior) is in the references file.
+
+## Escape hatch: pull a real card instead of authoring from scratch
+
+For anything beyond a single dimension + metric — combo charts, conditional formatting, pivot splits, click behavior, series colors — the cheapest **correct** path is to build it once in the Metabase UI and copy the result:
+
+```bash
+mb card get <id> --full --json | jq '.visualization_settings'
+```
+
+Paste that block into your `card create`/`update` body. The server produced it, so it's guaranteed valid for that `display`. This beats guessing keys from memory, and it's token-cheap (no schema dump).
+
+## Full key catalog
+
+The body above covers the high-frequency 90%. The complete per-display key tables — every `graph.*`/`pie.*`/`table.*`/… key, series settings, conditional formatting rules, pivot splits, the full `column_settings` formatting vocabulary, virtual-card (heading/text/link/iframe) settings, and click behavior — live in this skill's references file. Load it on demand, not by default:
+
+```bash
+mb skills get viz --full          # appends references/settings.md to this body
+mb skills path viz                # → the skill dir; then Read references/settings.md
+```
+
+## Don't
+
+- Don't invent `display` values (`bargraph`, `linechart`, `histogram`) — use the closed enum; the API accepts the typo and renders nothing.
+- Don't put numeric field ids in `graph.dimensions`/`pie.metric`/`scalar.field` etc. — they take **output column-name strings**.
+- Don't write a `column_settings` key as an object — it's a JSON **string** (`"[\"name\",\"COL\"]"`), inner quotes escaped.
+- Don't use the MBQL-5 field-ref order inside a `column_settings` `["ref", …]` key — that key uses the **legacy** `["field", id, opts]` order. Prefer the `["name", …]` form and sidestep it.
+- Don't expect a pre-flight to catch viz mistakes — there is none. Verify by reading the card back.
+- Don't hand-author complex charts when you can pull a working `visualization_settings` from a UI-built card.