@metabase/cli 0.1.17 → 0.2.0

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

@@ -0,0 +1,118 @@
+---
+name: native-sql
+description: Author native SQL queries with parameters (filter widgets) for the `mb` CLI. Native SQL is a query whose single stage is raw SQL (`mbql.stage/native`) instead of structured MBQL — the same query envelope, so it is pre-flight-validated and round-trips. Covers the shape, the four template-tag kinds (raw variable, field filter, snippet, card reference), the variable / optional-block / snippet / card-reference syntax, the field-filter-vs-variable decision, the field ref in a field-filter dimension, wiring a tag to a dashboard filter, and running with values. Triggers — "write a SQL question", "add a filter widget to my SQL", "parameterize this query", "use a field filter", "reference a saved question in SQL", "why does my variable return no rows".
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Native SQL
+
+**Prefer a structured query.** Native SQL is a Metabase query whose single stage is raw SQL (`mbql.stage/native`) instead of structured MBQL (`mbql.stage/mbql`) — both are the same query envelope (`mbql`). Reach for a native stage only when a structured query genuinely can't express it — engine-specific functions, CTEs, window logic beyond `offset`, hairy hand-tuned SQL — or when the user asks for SQL. If you can write it as a structured stage, do.
+
+General flag conventions, body-input precedence, `./.scratch`, and `mb uuid` mechanics live in `core` (`mb skills get core`).
+
+## The shape
+
+A native `dataset_query` is a query with one **native stage** — the `lib/type: "mbql/query"` envelope, a numeric `database`, and a single `mbql.stage/native` stage carrying the SQL string (`native`) plus a `template-tags` map:
+
+```json
+{
+  "lib/type": "mbql/query",
+  "database": 1,
+  "stages": [
+    {
+      "lib/type": "mbql.stage/native",
+      "native": "SELECT count(*) FROM orders WHERE {{status}} AND total > {{min_total}}",
+      "template-tags": { "status": { … }, "min_total": { … } }
+    }
+  ]
+}
+```
+
+This is the form a card stores and returns — author it. The CLI **pre-flight-validates** it — the envelope, the template-tag shapes, the field refs — through the usual `--print-schema → --dry-run → run` loop (`mbql`), and a saved card **round-trips** in exactly this shape: `mb card get <id> --full --json`, edit the `stages[0].native` string, send it straight back. Only the SQL string is opaque to pre-flight — a **SQL** syntax error surfaces just when you run it, not at `--dry-run`. A parameterless query needs no `template-tags` — just the `native` string.
+
+You may see an older flat form in cards created long ago — `{database, type:"native", native:{query}}`. The server still accepts it (it normalizes to the above) but it skips pre-flight and doesn't round-trip — **don't author it**.
+
+## Parameters are template tags
+
+Every `{{name}}` in the SQL must have a matching entry in the stage's `template-tags`, keyed by that name. **The three must agree exactly:** the `{{name}}` in SQL = the map key = the entry's `"name"` field. Names are case-sensitive (`{{Cat}}` ≠ `{{cat}}`). A `{{name}}` with no entry fails at run time; an unused entry is ignored.
+
+Four kinds of tag, by `type`:
+
+| Kind               | `type`                           | SQL syntax                    | What it is                                   |
+| ------------------ | -------------------------------- | ----------------------------- | -------------------------------------------- |
+| **Raw variable**   | `text` `number` `date` `boolean` | `WHERE total > {{min_total}}` | a literal substituted into the SQL           |
+| **Field filter**   | `dimension`                      | `WHERE {{status}}` (bare!)    | a smart filter widget bound to a real column |
+| **Snippet**        | `snippet`                        | `{{snippet: Active Rows}}`    | a reusable SQL fragment (`mb snippet`)       |
+| **Card reference** | `card`                           | `{{#42}}` or `{{#42-slug}}`   | another saved query, as a subquery           |
+
+Give each tag an `id` — mint one per tag with `mb uuid` (never hand-write one). Wrap any clause that should be droppable when its value is empty in **`[[ … ]]`**, keyword and all: `[[AND {{status}}]]`, not `AND [[{{status}}]]`. Only one level of nesting; a query using several optional `[[AND …]]` blocks needs a real `WHERE` first (e.g. `WHERE true [[AND {{a}}]] [[AND {{b}}]]`).
+
+## The decision that matters: field filter vs. raw variable
+
+This is the call agents get wrong. Default to a **field filter** whenever the tag filters a real table column.
+
+- A **raw variable** (`{{x}}`) is a dumb literal splice. You write the operator yourself: `WHERE status = {{x}}`. It gives a plain text/number/date box, no dropdown, no date picker, and it's what powers computed bits that aren't a column (`LIMIT {{n}}`, a threshold, an interpolated identifier).
+- A **field filter** (`type: dimension`) is a smart widget bound to a column via `dimension`. You write it **bare** — `WHERE {{status}}` — and Metabase expands it to the right SQL (`status IN (...)`, a `BETWEEN` for dates, etc.), driving a dropdown/date-picker sourced from the column's values. Writing `WHERE status = {{status}}` around a field filter **breaks the expansion** — the single most common native-SQL bug.
+
+Field filters only bind to a **real, connected database column** — not an expression, not an aggregate, not a subquery/CTE column. If the thing you're filtering isn't a physical column, it has to be a raw variable.
+
+## Template-tag bodies (the two you author most)
+
+**Field filter** — `dimension` binds a column, `widget-type` picks the widget:
+
+```json
+"status": {
+  "id": "9ddca4ca-3906-83fd-bc6b-8480ae9ab05e",
+  "name": "status",
+  "display-name": "Status",
+  "type": "dimension",
+  "dimension": ["field", {}, 141],
+  "widget-type": "string/="
+}
+```
+
+**`dimension` is a field ref: `["field", {options}, <field-id>]`** — options object **second**, id **third**, exactly the `mbql` rule. The legacy `["field", <id>, null]` shape (id first) that the UI and older docs show is **rejected by pre-flight** here (`must be the field options object`). Send `{}` for the options; the server fills in a `lib/uuid`. The field id comes from `table get <id> --include fields`.
+
+`widget-type` must suit the column's type and is a closed enum (same vocabulary as dashboard filter `type`): string ops (`string/=`, `string/!=`, `string/contains`, `string/starts-with`, …), number ops (`number/=`, `number/between`, `number/>=`, …), dates (`date/all-options`, `date/range`, `date/relative`, `date/month-year`, …), plus `category`, `id`, `boolean/=`, and the `location/*` set. Text column → a `string/*` or `category`; datetime → a `date/*`; numeric → a `number/*`. `date/all-options` is the most flexible date widget.
+
+**Raw variable** — no `dimension`, no `widget-type`:
+
+```json
+"min_total": {
+  "id": "35f1ecd4-d622-6d14-54be-750c498043cb",
+  "name": "min_total",
+  "display-name": "Minimum total",
+  "type": "number",
+  "required": true,
+  "default": "50"
+}
+```
+
+Snippet and card-reference bodies (and the full field list for every kind) are in `references/template-tags.md` — load it when you need them (`mb skills get native-sql --full`).
+
+## Snippets and card references
+
+- **Snippet** (`{{snippet: Name}}`): a shared SQL fragment stored via `mb snippet create --body '{"name":"Active Rows","content":"status = '\''active'\''"}'` — `content` is bare SQL, no wrapping. Reuse it across queries; edit it once. The tag body carries `snippet-id` + `snippet-name`.
+- **Card reference** (`{{#42}}`): inlines another saved query as a subquery — `SELECT * FROM {{#42}}` or `WITH x AS {{#42}} …`. The tag body carries `card-id`.
+- **Neither takes a parameter value.** A referenced card runs with **its own saved defaults** — you can't override its parameters from the parent query. Snippets are static text. Only raw variables and field filters are user-fillable.
+
+## Wiring, defaults, and running
+
+**Give a tag a default or a dropdown source** by declaring it in the card's `parameters` array (alongside `dataset_query`) — this is where `default`, and a `values_source_type` (`static-list` / `card`) live. Its `target` links back to the tag: `["dimension", ["template-tag", "status"]]` for a field filter, `["variable", ["template-tag", "min_total"]]` for a raw variable. (Metabase auto-derives basic `parameters` from the template tags, so you only declare them to add defaults or a value source.)
+
+**Run a saved card with values** via `card query`, whose `--parameters` is a JSON array of `{type, target, value}` — same `target` grammar:
+
+```bash
+mb card query 12 --parameters '[{"type":"string/=","target":["dimension",["template-tag","status"]],"value":"active"}]' --json
+```
+
+**Expose it as a dashboard filter** by mapping a dashboard parameter to the tag on the dashcard — the mapping `target` is the same `["dimension",["template-tag","status"]]` (field filter) or `["variable",["template-tag","status"]]` (raw variable). The dashboard-side mechanics (the `parameters` array and `parameter_mappings`) live in `core`.
+
+## Don't
+
+- Don't wrap a field filter in an operator (`WHERE col = {{ff}}`) — write it bare (`WHERE {{ff}}`).
+- Don't write the field-filter `dimension` in the legacy `["field", id, null]` shape — use `["field", {}, id]` (options second).
+- Don't author the flat `{type:"native", …}` form — send the native stage above.
+- Don't use native SQL for DDL or multiple statements — the editor is read-only, single-statement; `CREATE`/`UPDATE`/`;`-chained SQL is unsupported. To materialize a table, use a `transform`.
+- Don't expect `[[ ]]` to save you from a case/type mismatch — `WHERE plan = {{p}}` returns zero rows on a case-sensitive engine if the value's case is off; that's a value problem, not syntax.
+- Don't reach for native when a structured query fits — you lose the engine-independence and readability of an `mbql.stage/mbql` stage.

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
 ---
 
@@ -17,11 +17,11 @@ 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. 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, the `--print-schema` → `--dry-run` validation loop, and the MBQL-5 pre-flight that `transform create`/`update` run (legacy MBQL 4 and native sources skip it) — see `mbql` (**`mb skills get mbql`**). Pull a sample MBQL 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.
+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 `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`, `$$`).
+**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
 cat > ./.scratch/user_counts_by_signup_year.sql <<'SQL'
@@ -36,7 +36,7 @@ SQL
 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
 
@@ -124,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
 
@@ -162,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
 

package/skill-data/visualization/SKILL.md

@@ -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.
 
-Valid `display` values — the registered visualizations: `table`, `bar`, `line`, `area`, `row`, `pie`, `scalar`, `smartscalar`, `combo`, `pivot`, `funnel`, `map`, `scatter`, `waterfall`, `progress`, `gauge`, `object`, `sankey`, `boxplot`. The API types `display` as a plain string and accepts any value — it renders an unknown one as nothing. (`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.
+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 @@ Valid `display` values — the registered visualizations: `table`, `bar`, `line`
 | `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`                |

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

@@ -104,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/dist/add-collection-Dek6kiRI.mjs

@@ -1,11 +0,0 @@
-import "./notice-DyVl5aYB.mjs";
-import "./error-5H_tcfL8.mjs";
-import "./command-augment-DdZIfx1V.mjs";
-import "./runtime-BJtuxWM8.mjs";
-import "./capabilities-N0jo5U7S.mjs";
-import "./parse-id-D4LeTUsP.mjs";
-import "./poll-BpAJpvb-.mjs";
-import "./poll-task-TilgciQn.mjs";
-import { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView } from "./add-collection-C-t9SQBk.mjs";
-
-export { add_collection_default as default };

package/dist/auth-Kv2MRkRk.mjs

@@ -1,22 +0,0 @@
-import "./command-augment-DdZIfx1V.mjs";
-import { defineCommandGroup } from "./group-BNE_RiH5.mjs";
-
-//#region src/commands/auth/index.ts
-var auth_default = defineCommandGroup({
-	name: "auth",
-	description: "Authenticate against a Metabase instance",
-	defaultCommand: "login",
-	skills: [{
-		skill: "core",
-		purpose: "authentication and named profiles"
-	}],
-	subCommands: {
-		login: () => import("./login-Bt6j6yBM.mjs").then((m) => m.default),
-		status: () => import("./status-CmRgHTrV.mjs").then((m) => m.default),
-		list: () => import("./list-CvhVYOVl.mjs").then((m) => m.default),
-		logout: () => import("./logout-ANkL02p0.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { auth_default as default };