@metabase/cli 0.1.17 → 0.2.0

package/skill-data/dashboard/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: dashboard
+description: Build Metabase dashboards via the `mb` CLI — lay out dashcards on the 24-column grid (`{col,row,size_x,size_y}` math, per-chart default sizes) and turn cards into a filterable, cross-linked app. Covers wiring filters to cards (parameters + parameter_mappings), the field-filter vs. raw-variable target grammar, linked/cascading filters and their foreign-key requirement, cross-filtering, click-through, multi-series overlays, and tabs. The parameter type enum and whole-array replace semantics live in `core`. Triggers — "build a dashboard from these cards", "my dashboard is squished into half the width", "wire a filter to these cards", "make a filter cascade", "click a bar to filter the other charts", "add a dashboard tab", "add a second series", "why isn't my filter showing".
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Dashboard
+
+A dashboard starts as cards on a grid; it becomes an **app** when filters drive the cards, charts cross-filter each other, and clicks navigate. This skill owns both: the grid layout and the interactive layer.
+
+**`core` owns the transport mechanics** — the whole-array replace semantics (editing `dashcards` or `parameters` replaces the entire set; omitted entries are deleted; new cards use negative ids), `update-dashcard` for a single safe patch vs. `update --body` for a full replace, the closed `parameter.type` enum, and the `parameter-values` verb. Read it first (`mb skills get core`). **`visualization`** owns each card's chart and the full `click_behavior` key catalog.
+
+Inspect before you wire: `mb dashboard get <id> --json` hydrates `parameters`, `dashcards`, and `tabs`; `mb dashboard cards <id>` lists just the dashcards.
+
+## Layout: the grid is 24 columns — not 12
+
+Every dashcard carries `{col, row, size_x, size_y}` in grid units: `col` is 0-indexed from the left edge, `row` grows downward, and `col + size_x ≤ 24`. **Full-width is `size_x: 24` — Metabase's per-chart _default_ width of 12 is half a row.** A layout authored on the usual 12-column web-grid assumption crams the whole dashboard into the left half of the viewport. The server stores whatever geometry you send — overlaps and gaps included, no auto-fix.
+
+Default sizes (w×h): `scalar`/`smartscalar` 6×3, `pie` 12×8, `table`/`pivot`/`object` 12×9, `waterfall` 14×6, `sankey` 16×10, `heading` 24×1, `text` 12×3, every other chart 12×6.
+
+The standard shape — a KPI row of scalars across the full 24, charts in halves or thirds below, wide tables full-width:
+
+```jsonc
+"dashcards": [
+  { "id": -1, "card_id": 101, "col": 0,  "row": 0, "size_x": 6,  "size_y": 3 },  // 4 KPIs × 6 = 24
+  { "id": -2, "card_id": 102, "col": 6,  "row": 0, "size_x": 6,  "size_y": 3 },
+  { "id": -3, "card_id": 103, "col": 12, "row": 0, "size_x": 6,  "size_y": 3 },
+  { "id": -4, "card_id": 104, "col": 18, "row": 0, "size_x": 6,  "size_y": 3 },
+  { "id": -5, "card_id": 105, "col": 0,  "row": 3, "size_x": 12, "size_y": 6 },  // two halves
+  { "id": -6, "card_id": 106, "col": 12, "row": 3, "size_x": 12, "size_y": 6 },
+  { "id": -7, "card_id": 107, "col": 0,  "row": 9, "size_x": 24, "size_y": 9 }   // full-width table
+]
+```
+
+**Sanity-check before sending:** rows should fill to 24 and at least one card must end at `col + size_x = 24`. If nothing in the array crosses column 12, you've authored a 12-column layout — double every width.
+
+## The wiring loop: a filter is a parameter + a mapping per card
+
+A dashboard filter is one entry in the dashboard's `parameters` array **plus** a `parameter_mappings` entry on every dashcard it should control. A parameter with no mapping is an inert widget — the most common "my filter does nothing" cause.
+
+```jsonc
+// dashboard.parameters — the widget
+{ "id": "status", "name": "Status", "slug": "status", "type": "string/=" }
+
+// on each target dashcard — bind the widget to a column of that card
+{ "parameter_id": "status", "card_id": 42,
+  "target": ["dimension", ["field", 1779, null]] }
+```
+
+The `target` grammar depends on what the card is:
+
+| Card's query                | `target`                                     |
+| --------------------------- | -------------------------------------------- |
+| MBQL column                 | `["dimension", ["field", <field-id>, null]]` |
+| Native **field filter** tag | `["dimension", ["template-tag", "<tag>"]]`   |
+| Native **raw variable** tag | `["variable", ["template-tag", "<tag>"]]`    |
+
+(Field ids from `table get <id> --include fields`; native tags from `native-sql`.) Because editing replaces the whole set, adding a filter is read-modify-write: `dashboard get <id> --json`, append to `parameters` and to each dashcard's `parameter_mappings`, send the full arrays back. To wire one card without touching the rest, `update-dashcard <dash-id> <dashcard-id> --body '{"parameter_mappings":[…]}'`.
+
+## Choose the interaction
+
+Four distinct mechanisms — pick by what the user wants clicking or filtering to _do_:
+
+| Want                                               | Mechanism                                             |
+| -------------------------------------------------- | ----------------------------------------------------- |
+| One widget filters several cards                   | a **dashboard parameter** mapped to each card (above) |
+| One filter's choices narrow another's              | a **linked filter** (`filteringParameters`)           |
+| Clicking a chart filters the other charts          | **cross-filter** click behavior                       |
+| Clicking navigates to a question / dashboard / URL | **link** click behavior                               |
+
+### Linked (cascading) filters
+
+Make a child filter (City) show only values consistent with a parent (State) by listing the parent's id in the child parameter's `filteringParameters`:
+
+```json
+{ "id": "city", "type": "category", "filteringParameters": ["state"] }
+```
+
+Two hard constraints, both from the same root: **linked filters read table-metadata foreign keys only.** They ignore joins defined inside a saved question or model. So the parent and child columns must be connected by a FK set in metadata — if the cascade shows values it shouldn't, the FK is missing (fix it via `metadata`, then retry). And `filteringParameters` is **incompatible with a `values_source_type` of `static-list` or `card`** — a custom value source overrides the cascade, so Metabase clears the link. Leave the child's value source live (omit it) for linked filtering to work.
+
+### Cross-filtering (click a chart to filter the rest)
+
+Set the **driver** chart's whole-card click behavior to `crossfilter`, mapping the clicked value into a dashboard parameter; map that same parameter onto the **follower** cards normally. The driver stays unmapped to it (it emits the value; it doesn't consume it). `click_behavior` lives in the dashcard's `visualization_settings` (whole card) or `column_settings[<col>].click_behavior` (per column on tables), with **camelCase** keys:
+
+```json
+{
+  "click_behavior": {
+    "type": "crossfilter",
+    "parameterMapping": {
+      "status": {
+        "id": "status",
+        "source": { "type": "column", "id": "STATUS", "name": "Status" },
+        "target": { "type": "parameter", "id": "status" }
+      }
+    }
+  }
+}
+```
+
+### Click-through (navigate)
+
+```json
+{ "click_behavior": { "type": "link", "linkType": "dashboard",
+    "targetId": 7, "parameterMapping": { … } } }
+```
+
+`linkType` is `question` / `dashboard` (carry a `parameterMapping` to pass the clicked context) or `url` (a `linkTemplate` like `"https://app/orders/{{ORDER_ID}}"`, `{{Column}}` interpolated). The full `click_behavior`/`parameterMapping` key catalog is in `visualization`'s settings reference — don't hand-author a complex one; build it once in the UI and copy it (`mb dashboard get <id> --full --json`). Note: a **native-SQL card can't drill through** — only cross-filter and link click behaviors work on it.
+
+## Series, tabs, value sources
+
+**Multi-series overlay** — put several cards on one chart (**line / area / bar only**): the dashcard's `series` is an array of card ids in draw order (`"series": [43, 51]`). Sending it replaces the set; an empty array clears it. Patch with `update-dashcard`.
+
+**Tabs** — `tabs` is `[{ "name": "Overview", "position": 0 }, …]`; a dashcard joins a tab via `dashboard_tab_id`. Creating tabs and cards together uses **negative ids** (per `core`): give a new tab `id: -1`, point new dashcards at `dashboard_tab_id: -1`, and the create/update response returns the real ids. A filter widget only appears on a tab if it's mapped to at least one card on **that** tab.
+
+**Filter value source** (the dropdown behind a parameter) — omit `values_source_type` to pull live distinct values from the mapped column; `"static-list"` + `values_source_config.values` for a fixed list; `"card"` + `{card_id, value_field, label_field}` to source from a query. `mb dashboard parameter-values <id> <param-id> [--query <substr>]` previews what a widget will offer.
+
+## Gotchas
+
+- **Auto-connect / the missing map:** a filter that "does nothing" or "won't show" is almost always unmapped, or mapped only to cards on another tab.
+- **Time-grouping parameters** (`temporal-unit`) bind only to a datetime column in the query's **last** stage — add one after a time-bucketed summary and it can't attach.
+- **Required + default:** a `required: true` parameter with no `default` blocks its cards until a value is chosen; give it a `default` for expensive queries you don't want running unfiltered.
+- **Whole-array replace:** never send a partial `parameters`/`dashcards` array to `update` — you'll delete what you omit. Use `update-dashcard` for a single-card change.
+
+## Don't
+
+- Don't lay out on a 12-column assumption — full-width is `size_x: 24`; a layout where no card crosses column 12 renders in the left half of the viewport.
+- Don't declare a parameter and forget the per-card `parameter_mappings` — the widget won't filter anything.
+- Don't expect a linked filter to work off a model/question join, a custom column, or with a static/card value source — it needs a metadata FK and a live source.
+- Don't hand-author a complex `click_behavior` — copy a UI-built one.
+- Don't add a second `series` to a pie/scalar/table — it's line/area/bar only.

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

@@ -10,14 +10,14 @@ The front door for turning a raw database into clean tables, reusable definition
 
 A data project moves through stages. A user can start at any of them — detect where their data already is, don't assume.
 
-| Stage                       | What it does                                                                                              | Where the method lives                                    |
-| --------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
-| **Build clean tables**      | Raw, normalized source DB → a small set of wide, clean, analysis-ready tables (built as transforms)       | `references/building-clean-tables.md`                     |
-| **Define reusable metrics** | Clean tables → shared segments (saved filters), measures (saved calculations), metrics (official numbers) | `references/reusable-definitions.md`                      |
-| **Answer questions**        | Clean tables → a trustworthy plain-language written answer                                                | `references/answering-questions.md`                       |
-| **Build dashboards**        | Clean tables / definitions → charts and dashboards people look at                                         | the `visualization` skill (`mb skills get visualization`) |
+| Stage                       | What it does                                                                                              | Where the method lives                                                                       |
+| --------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| **Build clean tables**      | Raw, normalized source DB → a small set of wide, clean, analysis-ready tables (built as transforms)       | `references/building-clean-tables.md`                                                        |
+| **Define reusable metrics** | Clean tables → shared segments (saved filters), measures (saved calculations), metrics (official numbers) | `references/reusable-definitions.md`                                                         |
+| **Answer questions**        | Clean tables → a trustworthy plain-language written answer                                                | `references/answering-questions.md`                                                          |
+| **Build dashboards**        | Clean tables / definitions → charts and dashboards people look at                                         | the `visualization` skill (charts) + `dashboard` skill (grid layout, filters, interactivity) |
 
-The first three methods are references in this skill — read **only the one the current stage needs**: run `mb skills path data-workflow` and Read `references/<file>.md`. (`mb skills get data-workflow --full` appends all three at once — heavier; prefer the single Read.) "Build dashboards" is the standalone `visualization` skill because authoring a chart is a CLI capability in its own right.
+The first three methods are references in this skill — read **only the one the current stage needs**: run `mb skills path data-workflow` and Read `references/<file>.md`. (`mb skills get data-workflow --full` appends all three at once — heavier; prefer the single Read.) "Build dashboards" lives in two standalone skills — `visualization` for authoring each chart, `dashboard` for laying cards out on the grid and wiring filters and interactivity — both CLI capabilities in their own right. Load `dashboard` before composing any dashboard, even a plain no-filter layout: the grid geometry lives there.
 
 CLI mechanics come from the reference skills, not from here: `mb skills get core` (auth, inspection, the `field`/`table`/`library`/`segment`/`measure` verbs), `mbql` (query and definition bodies), `transform` (creating/running transforms). This skill owns the _judgment_ — which tables, which definitions, what to keep — and the conventions below.
 
@@ -88,19 +88,21 @@ The rules every stage follows. The reference files assume this contract rather t
 
 Don't make the user name a _stage_ — but do find out _where their data lives_ before going looking.
 
+**Data not in a database yet?** A local CSV gets in via `mb upload csv --file <path>` (creates a table + model); treat the result as a starting table and clean it with a transform if needed. Uploads must be admin-enabled — check `mb setting get uploads-settings --json` (`db_id: null` ⇒ not configured). See `core`'s **upload** quirk for the rest.
+
 **Ask before you crawl.** If you don't already know which database/schema/table the user means, ask — one plain question short-circuits a dozen tool calls. The asymmetry: if they name a **database**, ask which **schema**; if they name a **table**, ask which **database**. "If you don't know, no problem — I'll look" is the fallback, not the opener.
 
-**When you do crawl,** use `core`'s cheap, narrowest-first ladder (never whole-warehouse rollups): `mb db list` → `db schemas <id>` → `db schema-tables <id> <schema>` → `table list [--db-id]` → `table fields <id>` (or `table metadata <id>` for FK targets and dimensions — heavier). Have a _name_ rather than a tree to walk? `mb search <query> [--models] [--db-id]`. Need to know what's in a column? `mb field summary <id>` (counts) and `field values <id>` (sample values). If a database looks freshly connected or an expected table is missing, offer `mb db sync-schema <id> --wait` before concluding it doesn't exist.
+**When you do crawl,** use `core`'s cheap, narrowest-first ladder (never whole-warehouse rollups): `mb db list` → `db schemas <id>` → `db schema-tables <id> <schema>` → `table list [--db-id]` → `table fields <id>` (or `table get <id> --include fields --full` for FK targets and dimensions). Have a _name_ rather than a tree to walk? `mb search <query> [--models] [--db-id]`. Need to know what's in a column? `mb field summary <id>` (counts) and `field values <id>` (sample values). If a database looks freshly connected or an expected table is missing, offer `mb db sync-schema <id> --wait` before concluding it doesn't exist.
 
 **Read the shape to pick a stage.** Raw, normalized, SaaS-synced tables (many tables, coded columns, `*_field`/`*_choice` lookups)? → **build clean tables** first. Already wide, clean, human-readable ones? Then it depends on the goal:
 
-| What the user wants / what's there                                                                             | Stage                                                          |
-| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| "Clean up / flatten / make sense of" raw, normalized data; no clean tables yet                                 | Build clean tables → `references/building-clean-tables.md`     |
-| Clean tables exist; "make this reusable", "define active customers / revenue / MRR officially"                 | Define reusable metrics → `references/reusable-definitions.md` |
-| Clean tables exist; "answer this question", "who registered", "analyze / report on X" (wants a written answer) | Answer questions → `references/answering-questions.md`         |
-| Clean tables (and maybe definitions) exist; "chart this", "build a dashboard", "show me X over time"           | Build dashboards → `mb skills get visualization`               |
-| "Do the whole thing" / "set up analytics for X" from raw data                                                  | Start at build-clean-tables, then continue down the stages     |
+| What the user wants / what's there                                                                             | Stage                                                                             |
+| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| "Clean up / flatten / make sense of" raw, normalized data; no clean tables yet                                 | Build clean tables → `references/building-clean-tables.md`                        |
+| Clean tables exist; "make this reusable", "define active customers / revenue / MRR officially"                 | Define reusable metrics → `references/reusable-definitions.md`                    |
+| Clean tables exist; "answer this question", "who registered", "analyze / report on X" (wants a written answer) | Answer questions → `references/answering-questions.md`                            |
+| Clean tables (and maybe definitions) exist; "chart this", "build a dashboard", "show me X over time"           | Build dashboards → `visualization` (charts) + `dashboard` (layout, interactivity) |
+| "Do the whole thing" / "set up analytics for X" from raw data                                                  | Start at build-clean-tables, then continue down the stages                        |
 
 **Answer and dashboard are alternative endpoints, not a sequence.** Once tables are clean (and maybe defined), answering in prose and building a dashboard are two different things you can do with the data — route to whichever the goal calls for; neither has to precede the other.
 

package/skill-data/data-workflow/references/building-clean-tables.md

@@ -131,7 +131,7 @@ Then make the links real, not just implied:
 - **Wire foreign keys between your tables.** Mark each linking id as a foreign key pointing at the id it references — set the column's type to foreign-key and its target so Metabase itself knows the tables connect and can traverse them.
 - **Graft onto existing clean data** the user approved (step 3 / Phase 1): point the linking id at the existing table's id the same way. Link, don't duplicate.
 
-**Set the metadata — a transform's output starts blank, and these tables are Library-bound.** A fresh transform table has no descriptions, raw column names, and untyped columns. You worked it out while investigating; don't leave that knowledge stranded in this chat. Set it on the table so the data explains itself inside Metabase (search, the Question editor, Metabot) and is fit to publish. The mechanics — `mb field update` for semantic types / FK targets / display names, `mb table update` for table descriptions — and their footguns are in `core`; the calls about _what_ to set:
+**Set the metadata — a transform's output starts blank, and these tables are Library-bound.** A fresh transform table has no descriptions, raw column names, and untyped columns. You worked it out while investigating; don't leave that knowledge stranded in this chat. Set it on the table so the data explains itself inside Metabase (search, the Question editor, Metabot) and is fit to publish. The mechanics — `mb field update` for semantic types / FK targets / display names, `mb table update` for table descriptions, and the feature each edit unlocks — are in the `metadata` skill; the calls about _what_ to set:
 
 - **Semantic types — the highest-value piece.** A column's semantic type is what makes Metabase treat it right: `type/Email`, `type/Currency`/`type/Price`, `type/Category` (turns into a filter dropdown), `type/City`/`type/State`/`type/Country`, `type/CreationTimestamp`, `type/Description`. Set it on every column whose meaning you decoded. A typed column shows money as money, offers a filter dropdown, and lands on the right chart axis for everyone downstream; an untyped one is a guess.
 - **Descriptions.** A one-line description on each table and every non-obvious column.

package/skill-data/document/SKILL.md

@@ -22,11 +22,11 @@ mb document archive <id> --profile <name> --json         # soft-delete (PUT arch
 
 - `list` returns the standard envelope (`{data, returned, total}`). The compact item is `{id, name, collection_id, archived, creator_id, can_write}` and omits the (potentially huge) `document` body — pull the body with `get --full`.
 - `archive` is the only delete, mirroring `card` / `dashboard`. **Unarchive** with `mb document update <id> --body '{"archived":false}'`.
-- `update` is PATCH — send only the keys you want to change, and only these are accepted: `name`, `document`, `collection_id`, `collection_position`, `archived`. Replacing `document` replaces the **whole** body; there is no partial-node patch.
+- `update` is PATCH — send only the keys you want to change: `name`, `document`, `collection_id`, `collection_position`, `archived`, and `cards` (inline card creation works on update too, not just create — see below). Replacing `document` replaces the **whole** body; there is no partial-node patch.
 
 ## Node ids (`_id`)
 
-The editor anchors only these node types with an `_id` (a UUID): `paragraph`, `heading`, `codeBlock`, `orderedList`, `bulletList`, `blockquote`, `cardEmbed`, `supportingText`. **`create`/`update` require a non-empty `_id` on every node of those types** and reject a body missing any ("did not match expected schema"). Other node types (`doc`, `text`, `listItem`, `resizeNode`, `flexContainer`, …) take no `_id` and are left alone. Without them the editor backfills ids when the document opens, which makes a freshly-saved document show a spurious "unsaved changes" prompt.
+The editor anchors only these node types with an `_id` (a UUID): `paragraph`, `heading`, `codeBlock`, `orderedList`, `bulletList`, `blockquote`, `cardEmbed`, `supportingText`. **`create`/`update` require a non-empty `_id` on every node of those types** — the CLI validates before sending and rejects a body missing any (`every … node needs a non-empty string _id (mint with mb uuid)`). Other node types (`doc`, `text`, `listItem`, `resizeNode`, `flexContainer`, …) take no `_id` and are left alone. Without them the editor backfills ids when the document opens, which makes a freshly-saved document show a spurious "unsaved changes" prompt.
 
 Mint the ids with `mb uuid --count <n> --json` (→ `["…", …]`), one per id-bearing node, and set each as that node's `attrs._id`.
 
@@ -81,7 +81,7 @@ Every node is `{ "type": string, "attrs"?: object, "content"?: [nodes], "text"?:
 - **`resizeNode`** — wraps a single `cardEmbed` or `flexContainer` to make it resizable (no `_id`). `attrs: { "height": <px>, "minHeight": <px> }`, `content` is exactly one `cardEmbed`/`flexContainer`.
 - **`flexContainer`** — a horizontal row of 1–3 `cardEmbed` / `supportingText` cells side by side (no `_id`). `attrs.columnWidths` is an array of width percentages.
 - **`supportingText`** — a text column that sits next to a card inside a `flexContainer` (id-bearing); `content` is the usual block nodes (`paragraph`, `heading`, lists, …).
-- **`smartLink`** — an inline reference to a Metabase entity (renders as a live chip). Inline, atomic, no `_id`. `attrs: { "entityId": <id>, "model": <model>, "label": <string|null>, "href": <relative-path> }`. `model` ∈ `card`, `dataset`, `metric`, `dashboard`, `collection`, `table`, `database`, `document`, `transform`, `segment`, `measure`, `user`, `action`, `indexed-entity`.
+- **`smartLink`** — an inline reference to a Metabase entity (renders as a live chip). Inline, atomic, no `_id`. `attrs: { "entityId": <id>, "model": <model>, "label": <string|null>, "href": <relative-path> }`. `model` ∈ `card`, `dataset`, `metric`, `dashboard`, `collection`, `table`, `database`, `document`, `transform`, `segment`, `user`, `action`, `indexed-entity` (plus `measure` on v60+).
 - **`metabot`** — an inline Metabot prompt block.
 
 ## Embedding an existing card

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

@@ -16,8 +16,8 @@ Always run `status` (or `is-dirty` + `has-remote-changes`) before `import` or `e
 
 ```bash
 mb git-sync status              --profile <n> --json   # → branch, dirty, current task
-mb git-sync is-dirty            --profile <n> --json   # → {dirty: bool}; instance has unexported changes
-mb git-sync has-remote-changes  --profile <n> --json   # → {behind: bool}; remote has unimported commits
+mb git-sync is-dirty            --profile <n> --json   # → {is_dirty: bool}; instance has unexported changes
+mb git-sync has-remote-changes  --profile <n> --json   # → {has_changes: bool, remote_version, local_version, cached}; remote has unimported commits
 mb git-sync dirty               --profile <n> --json   # → list the dirty objects
 mb git-sync current-task        --profile <n> --json   # → in-flight task (or idle)
 ```
@@ -43,8 +43,8 @@ Pulls the configured branch and applies it to the instance. Polls until the task
 
 Workflow:
 
-1. Read state (above) — confirm `dirty: false` (or `--force` is intended).
-2. Confirm `has-remote-changes` reports there's actually something to import.
+1. Read state (above) — confirm `is_dirty: false` (or `--force` is intended).
+2. Confirm `has-remote-changes` reports `has_changes: true` — there's actually something to import.
 3. `git-sync import --branch <branch>` — runs to terminal status by default.
 
 ## Export (instance → remote)
@@ -67,7 +67,7 @@ Workflow:
 1. **Branch guard** (below) — confirm the instance isn't tracking `main`/`master`, or that the user has explicitly accepted exporting to it.
 2. Read state (above) — confirm `is-dirty` reports there's something to export.
 3. `git-sync export -m "..."` — pushes and polls.
-4. (Optional) `git-sync status` — verify `dirty: false` after.
+4. (Optional) `git-sync status` — verify `is_dirty: false` after.
 
 ### Branch guard: don't export to main/master without confirmation
 

package/skill-data/mbql/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: mbql
-description: Author and debug MBQL 5 query bodies for the `mb` CLI — the only hand-authorable query format. Covers the JSON shape (flat numeric-id stages, options-object-second clauses, optional lib/uuid), joins and FK traversal, multi-stage pipelines, aggregation naming, the flat-vs-legacy-envelope footgun, and the print-schema → dry-run → run validation loop. Use when writing or fixing any query body — `mb query`, a card's `dataset_query`, a transform's `source.query`, or a segment/measure `definition` — or when `--dry-run`/run reports validation errors. Triggers — "write an MBQL query", "the dataset_query is wrong", "aggregate and group by", "join two tables", "month-over-month".
+description: Author and debug MBQL query bodies for the `mb` CLI — the only hand-authorable query format. Covers the JSON shape (flat numeric-id stages, options-object-second clauses, optional lib/uuid), joins and FK traversal, multi-stage pipelines, aggregation naming, the flat-vs-legacy-envelope footgun, and the print-schema → dry-run → run validation loop. Use when writing or fixing any query body — `mb query`, a card's `dataset_query`, a transform's `source.query`, or a segment/measure `definition` — or when `--dry-run`/run reports validation errors. Triggers — "write an MBQL query", "the dataset_query is wrong", "aggregate and group by", "join two tables", "month-over-month".
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
-# MBQL 5
+# MBQL
 
-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).
+MBQL is the query format you author by hand — it has a bundled JSON Schema, so the CLI pre-flight-validates it before sending. A native SQL query is **also** MBQL: its single stage is `mbql.stage/native` (raw SQL) instead of `mbql.stage/mbql` (structured), so it's pre-flight-validated the same way (its SQL string aside) — see `native-sql`. Only the legacy flat forms below skip validation.
 
-Prefer MBQL over native SQL: portable across warehouse engines and pre-flight-validated. Try it first; fall back to native SQL when MBQL can't express what you need, or when an MBQL body keeps failing server-side and you can't resolve it.
+Prefer a **structured** stage over a native SQL stage: portable across warehouse engines. Try it first; fall back to a native stage when structured MBQL can't express what you need, or when a structured body keeps failing server-side and you can't resolve it. For native SQL with parameters (template tags, field filters, snippets), load `native-sql`.
 
 General flag conventions, body-input precedence, output flags, `./.scratch`, and `mb uuid` mechanics live in `core` (`mb skills get core`).
 
@@ -47,7 +47,7 @@ Every clause is `[op, {options}, ...args]`. The options object is element **1**,
 ["asc",   {}, ["field", {}, 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 legacy 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`.
 
@@ -89,15 +89,15 @@ mb query --file q.json --profile <n> --json                     # 3. validate +
 - `Invalid :expression reference: no expression named "X"` (or an invalid `:aggregation` reference) → a **ref** points to an expression name / aggregation `lib/uuid` that isn't defined in the query; fix the target string.
 - `Duplicate :lib/uuid` → you reused a `lib/uuid`. Omit them (the server mints unique ones) or give each clause a distinct value.
 
-A successful run emits the compact envelope by default: `data.rows` + slim `data.cols` (`name`, `display_name`, `base_type`, `semantic_type`). Pass `--full` for the raw `/api/dataset` envelope (`results_metadata`, `native_form`, per-column fingerprints/`field_ref`) only when you need that metadata; `--fields data.rows` narrows to rows alone. `mb query` also runs a **native** body — `{database, type:"native", native:{query:"SELECT …"}}` — which skips pre-flight; the quickest way to eyeball warehouse data.
+A successful run emits the compact envelope by default: `data.rows` + slim `data.cols` (`name`, `display_name`, `base_type`, `semantic_type`). Pass `--full` for the raw `/api/dataset` envelope (`results_metadata`, `native_form`, per-column fingerprints/`field_ref`) only when you need that metadata; `--fields data.rows` narrows to rows alone. `mb query` also runs a native query — author it as an `mbql.stage/native` stage (pre-flight-validated like any MBQL body; see `native-sql`).
 
 `--skip-validate` bypasses 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`. Same flag exists on `card create/update` and `transform create/update`.
 
-## Where MBQL 5 is consumed
+## Where the query is consumed
 
-The same body and 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.
+The same body and pre-flight apply everywhere a query is embedded. Each pre-flights only when the value is the `mbql/query` shape (`lib/type: "mbql/query"`); legacy shapes skip it; `--skip-validate` bypasses.
 
-| Command                                 | MBQL 5 lives at                                | Notes                                       |
+| Command                                 | The query 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 |
@@ -107,7 +107,7 @@ The same body and pre-flight apply everywhere a query is embedded. Each pre-flig
 
 ## 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**:
+The most common mistake. The legacy shape `{ "type": "query", "database": N, "query": {…} }` looks similar but is wrong. `dataset_query` (and `source.query`, and `definition`) **is the `mbql/query` value itself**:
 
 ```json
 "dataset_query": {
@@ -118,16 +118,16 @@ The most common mistake. The legacy MBQL 4 shape `{ "type": "query", "database":
 }
 ```
 
-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 reached the server it would store silently and fail at run time with `Initial MBQL stage must have either :source-table or :source-card`.
+No `type:"query"` wrapper, no `query:` nesting. If you wrap the query inside a legacy envelope the CLI rejects it pre-send with a `ConfigError` (no `--skip-validate` gets it past). If it 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
+## Legacy formats you may encounter
 
-Anything not `lib/type: "mbql/query"` is sent as-is and normalized server-side:
+Older Metabase servers used a different query envelope (sometimes called MBQL 4 / "legacy MBQL"); the `mbql/query` shape above is what recent servers store and return. You won't author the legacy shapes, but you may see them in queries created long ago. Anything not `lib/type: "mbql/query"` is sent as-is and normalized server-side — you lose validation, so don't author these:
 
-- **Legacy MBQL 4** — `{ "type": "query", "database": N, "query": { "source-table": T, … } }`
-- **Native SQL** — `{ "type": "native", "database": N, "native": { "query": "SELECT …" } }`
+- **Legacy structured** — `{ "type": "query", "database": N, "query": { "source-table": T, … } }`
+- **Flat native** — `{ "type": "native", "database": N, "native": { "query": "SELECT …" } }` — the server accepts it, but author the native stage instead (`native-sql`).
 
-`mb query --file probe.json` runs these directly; `--dry-run` on them returns `{ ok: true, errors: [] }`. Don't author MBQL 4 by hand — build a legacy or complex query in the Metabase UI and pull the body with `mb card get <id> --full --json` / `mb transform get <id> --full --json`.
+`mb query --file probe.json` runs these directly; `--dry-run` on them returns `{ ok: true, errors: [] }`. Don't author them by hand — build a legacy or complex query in the Metabase UI and pull the body with `mb card get <id> --full --json` / `mb transform get <id> --full --json` (which returns the `mbql/query` shape).
 
 ## Joins and FK traversal
 
@@ -193,7 +193,7 @@ Later stages address the first stage's aggregation by the `name` you gave it (`"
 
 ## Naming aggregation output columns
 
-Default MBQL 5 aggregations materialize as `count`, `count_where`, `avg`, `avg_2`, `sum`, … — fine for an ad-hoc run, ugly for a transform target table or card column. Set `name` (the warehouse column name) and `display-name` (the UI header) in the aggregation's options:
+Default aggregations materialize as `count`, `count_where`, `avg`, `avg_2`, `sum`, … — fine for an ad-hoc run, ugly for a transform target table or card column. Set `name` (the warehouse column name) and `display-name` (the UI header) in the aggregation's options:
 
 ```json
 ["count", { "name": "shipments_shipped", "display-name": "Shipments shipped" }]

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

@@ -1,4 +1,4 @@
-# MBQL 5 operator reference
+# MBQL 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 —
@@ -240,8 +240,9 @@ positional arg is the default.)
 - 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`.
+  `day-of-month`, `day-of-year`, `week-of-year`, `month-of-year`, `quarter-of-year`,
+  `year-of-era`, `second-of-minute`. (The `*-iso`/`*-us` variants are `temporal-extract`
+  operator modes, not field-option bucketing units.)
 
 ```json
 ["field", { "temporal-unit": "month" }, 22]

package/skill-data/metadata/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: metadata
+description: Set Metabase field and table metadata via the `mb` CLI — semantic types, foreign-key targets, dropdown/scan behavior, column visibility, and display names. The point is the causal chain — one metadata edit unlocks a downstream feature (a FK target enables joins and linked filters; `has_field_values` picks the filter widget; `visibility_type` can block queries). Covers `field update` / `table update`, the writable-vs-read-only split, the semantic-type catalog, why semantic types are labels not casts (and how to actually cast), and sync-vs-scan-vs-fingerprint. Triggers — "set this column as currency / email / a category", "mark this as a foreign key", "make this column a dropdown", "why doesn't the query builder suggest a join", "hide this column", "set the entity key".
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Metadata
+
+Metabase reads the raw column types from your warehouse; **metadata** is the layer you edit on top to make columns behave well — the right filter widget, joins, formatting, maps. You set it per-column with `mb field update <id>` and per-table with `mb table update <id>`. Both are **PATCH** — send only the keys you're changing.
+
+Metadata is a small set of fields with large, indirect effects. Get the field ids from `mb table get <id> --include fields` (or `mb table fields <id>`); inspect a column's shape with `mb field get <id>`, its live cardinality with `mb field summary <id>`, its cached distinct set with `mb field values <id>`. General flag/output/body mechanics live in `core`.
+
+## The causal chain — set X, unlock Y
+
+This is the whole point of the skill. Each edit below is a key in the `field update` (or `table update`) body; the value change is what turns a feature on.
+
+| Set (via `field update`)                                             | Unlocks / does                                                                                                                                 |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `semantic_type: "type/PK"`                                           | marks the row's identity key — enables record/detail view, and lets other tables' FKs point here                                               |
+| `semantic_type: "type/FK"` **+** `fk_target_field_id: <pk field id>` | the join relationship — implicit FK joins in queries (`mbql` `source-field`), query-builder join suggestions, and dashboard **linked filters** |
+| `semantic_type: "type/Currency"` / `type/Email` / `type/City` / …    | correct display formatting and the matching filter widget (and region/pin maps for location types)                                             |
+| `has_field_values: "list"` (or `"auto-list"`)                        | a **dropdown** filter widget, backed by a scanned distinct-value set                                                                           |
+| `has_field_values: "search"`                                         | a **search box** (no value set stored) — for high-cardinality columns                                                                          |
+| `has_field_values: "none"`                                           | a plain input box, no dropdown                                                                                                                 |
+| `visibility_type: "sensitive"` or `"retired"`                        | **blocks queries** that touch the field — not a UI hint, an error                                                                              |
+| `visibility_type: "hidden"`                                          | removes the column from the query builder and data reference (SQL can still read it — **not access control**)                                  |
+| `visibility_type: "details-only"`                                    | hidden in table views, shown in the single-record detail view (for long blobs)                                                                 |
+| `coercion_strategy: <strategy>`                                      | **actually casts** the column — the only entry here that changes the value's type (below)                                                      |
+| `display_name` / `description`                                       | the human label and help text shown everywhere                                                                                                 |
+
+`table update` carries the table-level equivalents: `display_name`, `description`, `visibility_type` (`hidden` / `technical` / `cruft` — hides the whole table from the builder), `field_order`, and `entity_type`.
+
+## Foreign keys are the highest-leverage edit
+
+A FK relationship is what makes a warehouse browsable. Set it in **two keys on the FK column**, in one PATCH:
+
+```bash
+mb field update 1711 --body '{"semantic_type":"type/FK","fk_target_field_id":1684}' --profile <n> --json
+```
+
+`1711` is `orders.customer_id`; `1684` is `customers.id` (which should itself be `type/PK`). Once set:
+
+- Queries can pull columns from the related table with no explicit join — `["field", {"source-field": 1711}, 1682]` in MBQL (see `mbql`).
+- Dashboard **linked filters** become possible (a State filter narrowing a City filter). **Linked filters read only these table-metadata FKs** — never a join you wrote inside a saved question — which is why a linked filter that "shows values it shouldn't" almost always means the FK isn't set in metadata. (See `dashboard`.)
+
+Removing the `type/FK` semantic type auto-clears `fk_target_field_id`. Point a FK only at a field in the **same database** — v60+ rejects a cross-database target; v58–v59 accept it silently and leave a broken relationship.
+
+## Semantic types are labels, not casts
+
+The commonest misconception. `semantic_type: "type/Quantity"` on a text column does **not** make it a number — it changes formatting and widget choice, nothing about the stored value. Sorting still sorts as text.
+
+To genuinely change the type, use **`coercion_strategy`**, which casts `base_type` → an `effective_type` (e.g. a Unix-epoch integer read as a timestamp, or a numeric string read as a number):
+
+```bash
+mb field update 42 --body '{"coercion_strategy":"Coercion/UNIXSeconds->DateTime"}' --profile <n> --json
+```
+
+`base_type`, `effective_type`, and the physical `name` are **read-only** — set by warehouse sync, never editable here. For a durable transformation (splitting, combining, recomputing columns), build a `transform` rather than leaning on coercion.
+
+The full semantic-type catalog — every value grouped by the base type it attaches to, plus the `has_field_values` and `visibility_type` value tables and the exact writable-key lists — is in `references/semantic-types.md` (`mb skills get metadata --full`).
+
+## Sync, scan, fingerprint — three different refreshes
+
+When a column looks stale or missing, know which one you need (`db` verbs, mechanics in `core`):
+
+- **Sync** (`mb db sync-schema <id> --wait`) — re-reads table/column **structure** (new tables, new columns, types). Run after a schema change.
+- **Scan / rescan** (`mb db rescan-values <id>`) — refreshes the **distinct-value sets** behind dropdown filters. Run when a `list` column's values changed but its dropdown is stale.
+- **Fingerprint** — value-distribution stats (min/max, null count) computed on a sample; drives smart defaults. Refreshed by sync; not a separate CLI verb.
+
+A newly connected database or a missing expected column usually just needs a `sync-schema --wait` before you conclude anything.
+
+## Don't
+
+- Don't expect a `semantic_type` to cast — it's a label. Use `coercion_strategy`, or a `transform`.
+- Don't edit `name`, `base_type`, or `effective_type` — they're read-only from sync.
+- Don't treat `visibility_type: hidden` as security — it only hides from the builder; native SQL still reads the column. Real restriction is a permissions concern, outside the CLI.
+- Don't set a `type/City` / `type/State` filter and expect a map or clean dropdown if the values are inconsistent (abbreviations mixed with full names) — fix the values first (a `transform`), then the metadata.
+- Don't blame the data when a dashboard linked filter misbehaves — check the FK is set here first.

package/skill-data/metadata/references/semantic-types.md

@@ -0,0 +1,83 @@
+# Metadata — full reference
+
+The semantic-type catalog, the `has_field_values` / `visibility_type` value tables, and the exact writable-key lists for `field update` and `table update`. All values are strings in JSON (`"type/Currency"`). Unknown values are rejected — a new server type surfaces as a parse error, a deliberate signal.
+
+## Semantic types by base type
+
+Assign the one that matches the column's meaning. Grouped by the base type it belongs on; assigning a numeric semantic type to a text column is legal but only affects formatting, not behavior.
+
+**Relations (any type)**
+`type/PK` (entity key) · `type/FK` (needs `fk_target_field_id`)
+
+**Text — categorical & descriptive**
+`type/Category` · `type/Enum` · `type/Name` · `type/Title` · `type/Description` · `type/Comment` · `type/Source`
+
+**Text — communication & links**
+`type/Email` · `type/URL` · `type/ImageURL` · `type/AvatarURL` · `type/IPAddress`
+
+**Text — business entities**
+`type/User` · `type/Author` · `type/Owner` · `type/Product` · `type/Company` · `type/Subscription`
+
+**Location** (text unless noted)
+`type/City` · `type/State` · `type/Country` · `type/ZipCode` · `type/Latitude` (numeric) · `type/Longitude` (numeric) · `type/Coordinate` (numeric) · `type/Address`
+
+**Numeric — quantities & ratios**
+`type/Quantity` · `type/Score` · `type/Percentage` · `type/Share` · `type/Duration`
+
+**Numeric — money**
+`type/Currency` · `type/Price` · `type/Income` · `type/Cost` · `type/Discount` · `type/GrossMargin`
+
+**Temporal** (each has `…Timestamp` / `…Time` / `…Date` variants)
+`type/CreationTimestamp` · `type/UpdatedTimestamp` · `type/JoinTimestamp` · `type/CancelationTimestamp` · `type/DeletionTimestamp` · `type/Birthdate`
+
+**Structured**
+`type/Structured` · `type/SerializedJSON` · `type/XML`
+
+Location maps need clean inputs: lat/long must be numeric; `City`/`State`/`Country` must hold consistent, correctly-spelled values (and usually a scanned value set) to render region maps.
+
+## `has_field_values`
+
+Controls the filter widget and whether Metabase stores a distinct-value set (scanned from the column).
+
+| Value       | Widget      | Value set stored?                                 | Use for                                          |
+| ----------- | ----------- | ------------------------------------------------- | ------------------------------------------------ |
+| `list`      | dropdown    | yes (kept even if cardinality grows)              | low-cardinality columns you want as a picker     |
+| `auto-list` | dropdown    | yes (sync-assigned; reverts if too many distinct) | the default Metabase picks automatically         |
+| `search`    | search box  | no                                                | high-cardinality text (names, emails)            |
+| `none`      | plain input | no                                                | free-form values                                 |
+| `null`      | inferred    | —                                                 | let sync decide (you rarely set this explicitly) |
+
+A `list`/`auto-list` column's dropdown is refreshed by `mb db rescan-values <db-id>`.
+
+## `visibility_type` (field)
+
+| Value          | Effect                                                                                                          |
+| -------------- | --------------------------------------------------------------------------------------------------------------- |
+| `normal`       | default — visible everywhere                                                                                    |
+| `details-only` | hidden in table views; shown in the single-record detail view (long text / JSON blobs)                          |
+| `hidden`       | removed from the query builder and data reference — **UI only, not access control** (native SQL still reads it) |
+| `sensitive`    | **queries touching the field error** — stronger than hidden                                                     |
+| `retired`      | auto-set for dropped columns; **queries error**                                                                 |
+
+## `visibility_type` (table)
+
+`hidden` · `technical` · `cruft` — all hide the table from the query builder and data reference (degrees of "don't show this"). `null` is normal.
+
+## Writable keys
+
+Everything else on a field/table (physical `name`, `base_type`, `effective_type`, `active`, ids, timestamps) is read-only, set by sync.
+
+**`PUT /api/field/:id` (`mb field update`)**
+`display_name` · `description` · `caveats` · `points_of_interest` · `semantic_type` · `coercion_strategy` · `fk_target_field_id` · `visibility_type` · `has_field_values` · `settings` · `nfc_path` · `json_unfolding`
+
+**`PUT /api/table/:id` (`mb table update`)**
+`display_name` · `description` · `visibility_type` · `field_order` (`database` / `alphabetical` / `custom` / `smart`) · `entity_type` · `caveats` · `points_of_interest` · `show_in_getting_started` · `owner_user_id` / `owner_email` (ownership) · `data_layer` / `data_authority` / `data_source` (data-governance tiers) · `collection_id` (v62+)
+
+## Coercion strategies (common)
+
+Cast a `base_type` to a more useful `effective_type`. The value must be compatible with the column's base type and is driver-dependent (an unsupported one 400s at update).
+
+- Epoch numbers → datetime: `Coercion/UNIXSeconds->DateTime`, `Coercion/UNIXMilliSeconds->DateTime`, `Coercion/UNIXMicroSeconds->DateTime`, `Coercion/UNIXNanoSeconds->DateTime`
+- ISO-8601 strings → temporal: `Coercion/ISO8601->DateTime`, `Coercion/ISO8601->Date`, `Coercion/ISO8601->Time`
+- Numeric strings → number: `Coercion/String->Integer`, `Coercion/String->Float`
+- Narrowing: `Coercion/Float->Integer`, `Coercion/DateTime->Date`