@metabase/cli 0.1.16 → 0.1.18

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

@@ -6,51 +6,23 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 # git-sync (representations ↔ instance)
 
-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/*`.
+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/*`. Only collections flagged for sync serialize; everything else is local-only.
 
-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.
+This skill covers the import/export workflow. Flag conventions and auth setup live in `core` (`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 `visualization` 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
-
-The set of directories under sync is governed by which **collections** carry `is_remote_synced: true`. Every collection so flagged serializes to its own folder under `collections/` in the repo; everything outside that set is local-only. The CLI exposes per-collection toggles that route to the underlying bulk endpoint (`PUT /api/ee/remote-sync/settings`):
-
-```bash
-mb git-sync add-collection    <collection-id> --profile <n> --json
-mb git-sync remove-collection <collection-id> --profile <n> --json
-```
-
-`<collection-id>` is a **positive integer**. The bulk endpoint's schema is `pos-int? → boolean`; nano-id / `root` / `trash` refs (which `collection get` accepts) are not supported here. Get the id from `mb collection list --profile <n> --json` first.
-
-Both verbs return `{ success: true, task_id?: <id> }`. The optional `task_id` only appears when the toggle triggered a follow-up task (e.g., a finalization import after switching to read-only mode); for a normal add/remove in read-write, expect `{ success: true }` and nothing else.
-
-**Cascade.** A toggle on a parent cascades to every descendant by `location` prefix — `add-collection 4` flips `4` plus every collection nested under it. `remove-collection 4` is the symmetric inverse. There is no per-leaf-only mode.
-
-**Mode prerequisite.** The server rejects toggles while `remote-sync-type` is `:read-only` (the install default). If `mb git-sync add-collection 12` returns `Metabase returned 400 … Cannot change synced collections when remote-sync-type is read-only.`, switch first with:
-
-```bash
-mb setting set remote-sync-type '"read-write"' --profile <n>
-```
-
-(Mind the inner double quotes — `setting set` parses the value as strict JSON.) The server also rejects switching to `:read-only` while the Remote Sync collection is dirty; export or `--force` import first if you're going the other way.
-
-**Verifying the result.** The CLI's `Collection` schema doesn't yet expose `is_remote_synced`, so `collection get --json` won't show the flag. The pragmatic confirmation paths are:
-
-- `mb git-sync is-dirty --profile <n> --json` after editing a card in the now-synced collection — a `true` reading proves it's tracked.
-- The Metabase Admin UI's Remote Sync page renders the per-collection toggles.
-
-## Read state before mutating
+## Precondition: read state before mutating
 
 Always run `status` (or `is-dirty` + `has-remote-changes`) before `import` or `export`. Importing on a dirty instance silently rejects unless you pass `--force`; exporting when the instance is behind the remote pushes a stale state.
 
 ```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)
 ```
 
-**Clean up before exporting.** If you've created entities you intend to delete (a failed transform you're going to retry, a card you authored to test a body shape, a draft dashboard) — do the deletes _before_ the first `git-sync export`. Once committed, the cleanup needs a second commit, and the failed entity stays visible in `git log` forever. For the transform case specifically, prefer `transform update <id>` over `delete + create` so iteration never produces "broken-then-fixed" pairs in git history; see the `transform` skill, "Iterating on a failing transform".
+**Clean up before exporting.** If you've created entities you intend to delete (a failed transform you're going to retry, a card you authored to test a body shape, a draft dashboard) — do the deletes _before_ the first `git-sync export`. Once committed, the cleanup needs a second commit, and the failed entity stays visible in `git log` forever. For transforms, prefer `transform update <id>` over delete + create (see the `transform` skill).
 
 ## Import (remote → instance)
 
@@ -71,8 +43,8 @@ Pulls the configured branch and applies it to the instance. Polls until the task
 
 Workflow:
 
-1. `git-sync status` — confirm `dirty: false` (or `--force` is intended).
-2. `git-sync has-remote-changes` — confirm 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)
@@ -93,9 +65,9 @@ Pushes Metabase-side changes back to the configured remote. `-m` is the commit m
 Workflow:
 
 1. **Branch guard** (below) — confirm the instance isn't tracking `main`/`master`, or that the user has explicitly accepted exporting to it.
-2. `git-sync is-dirty` — confirm there's something to export.
+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
 
@@ -131,6 +103,34 @@ mb git-sync cancel-task --profile <n>      # cancel the in-flight task
 
 Use `wait` after `import --no-wait` / `export --no-wait`. Use `cancel-task` if a git-sync task hangs and you want to abandon it.
 
+## Adding / removing a directory (collection) to sync
+
+The set of directories under sync is governed by which **collections** carry `is_remote_synced: true`. Every collection so flagged serializes to its own folder under `collections/` in the repo; everything outside that set is local-only. The CLI exposes per-collection toggles that route to the underlying bulk endpoint (`PUT /api/ee/remote-sync/settings`):
+
+```bash
+mb git-sync add-collection    <collection-id> --profile <n> --json
+mb git-sync remove-collection <collection-id> --profile <n> --json
+```
+
+`<collection-id>` is a **positive integer** (the bulk endpoint's schema is `pos-int? → boolean`; nano-id / `root` / `trash` refs are not supported). Get the id from `collection list` (see `core`).
+
+Both verbs return `{ success: true, task_id?: <id> }`. The optional `task_id` only appears when the toggle triggered a follow-up task (e.g., a finalization import after switching to read-only mode); for a normal add/remove in read-write, expect `{ success: true }` and nothing else.
+
+**Cascade.** A toggle on a parent cascades to every descendant by `location` prefix — `add-collection 4` flips `4` plus every collection nested under it. `remove-collection 4` is the symmetric inverse. There is no per-leaf-only mode.
+
+**Mode prerequisite.** The server rejects toggles while `remote-sync-type` is `:read-only` (the install default). If `mb git-sync add-collection 12` returns `Metabase returned 400 … Cannot change synced collections when remote-sync-type is read-only.`, switch first with:
+
+```bash
+mb setting set remote-sync-type '"read-write"' --profile <n>
+```
+
+(`setting set` parses the value as strict JSON — mind the inner double quotes; see `core`.) The server also rejects switching to `:read-only` while the Remote Sync collection is dirty; export or `--force` import first if you're going the other way.
+
+**Verifying the result.** The CLI's `Collection` schema doesn't yet expose `is_remote_synced`, so `collection get --json` won't show the flag. The pragmatic confirmation paths are:
+
+- `mb git-sync is-dirty --profile <n> --json` after editing a card in the now-synced collection — a `true` reading proves it's tracked.
+- The Metabase Admin UI's Remote Sync page renders the per-collection toggles.
+
 ## Don't (git-sync-specific)
 
 - Don't run `git-sync import --force` or `git-sync export --force` without explicit user confirmation. Both are lossy — `--force` import discards instance-side work, `--force` export overwrites the remote branch.
@@ -138,4 +138,4 @@ Use `wait` after `import --no-wait` / `export --no-wait`. Use `cancel-task` if a
 - Don't author content directly via `card create` / `transform create` and then assume `git-sync export` will commit it cleanly — the instance and repo can drift if you mix direct API writes with sync-tracked changes. If you do, follow direct writes immediately with `git-sync export -m "..."` to keep them in step.
 - Don't omit `-m` on `export` if the user wants a meaningful commit message — the default server-generated message is generic.
 - Don't `git-sync export` to `main`/`master` without explicit user confirmation — sync work is conventionally on a feature branch. See "Branch guard" above.
-- Don't reach for `mb setting set` to mark a collection as remote-synced — that endpoint writes single-key settings, not the bulk `collections` map. Use `mb git-sync add-collection <id>` / `mb git-sync remove-collection <id>` (see "Adding / removing a directory (collection) to sync" above), and remember the toggle cascades to descendants.
+- Don't reach for `mb setting set` to mark a collection as remote-synced — that endpoint writes single-key settings, not the bulk `collections` map. Use `mb git-sync add-collection <id>` / `mb git-sync remove-collection <id>` (above), and remember the toggle cascades to descendants.

package/skill-data/mbql/SKILL.md

@@ -1,16 +1,16 @@
 ---
 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 numeric-id stages), the options-object-always-second clause rule, when lib/uuid is needed (optional - only to reference a clause), the print-schema/dry-run/run loop, where MBQL 5 is consumed (mb query, card dataset_query, transform source.query, measure/segment definition), the flat-vs-legacy-envelope footgun, joins and FK traversal, multi-stage pipelines, naming aggregation columns. Load when 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", "join two tables", "month-over-month", or any `--dry-run` / `mb query` work.
+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, and output flags live in the `core` skill (`mb skills get core`).
+General flag conventions, body-input precedence, output flags, `./.scratch`, and `mb uuid` mechanics live in `core` (`mb skills get core`).
 
 ## The shape
 
@@ -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`.
 
@@ -64,11 +64,7 @@ Set an explicit `lib/uuid` only when you must **reference a clause from elsewher
 
 (`AGG_UUID` is both the aggregation's own `lib/uuid` and the string the ref points at — one value, by string equality. Every other clause omits its UUID. Expression refs work the same way but key off the expression's `lib/expression-name` string, so expressions rarely need an explicit `lib/uuid`.)
 
-When you do need one, **always mint it with `mb uuid` — never write, guess, or copy a UUID yourself.** A hand-authored value is rejected pre-flight as not-a-v4 (`"a1"`, `"uuid-1"`, `"agg-uuid-001"` → `must be a UUID v4 (RFC 4122) — run \`mb uuid\``), or if it looks valid risks colliding with another clause. Only `mb uuid`gives genuine, unique v4s — mint just the few you reference (also covers native template-tag ids and any other`format: "uuid"` slot):
-
-```bash
-mb uuid --count 2 --json     # mint only the clauses you actually reference
-```
+When you do need one, **always mint it with `mb uuid` — never write, guess, or copy a UUID yourself.** A hand-authored value is rejected pre-flight as not-a-v4 (`"a1"`, `"uuid-1"`, `"agg-uuid-001"` → ``must be a UUID v4 (RFC 4122) — run `mb uuid` ``), or if it looks valid risks colliding with another clause. Mint just the few you reference (`mb uuid --count 2 --json`; this also covers native template-tag ids and any other `format: "uuid"` slot).
 
 ## Authoring loop: print-schema → dry-run → run
 
@@ -93,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 |
@@ -111,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": {
@@ -122,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
 
@@ -197,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" }]
@@ -213,11 +209,3 @@ mb skills path mbql           # → the skill dir; then Read references/operator
 ```
 
 `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 mint a `lib/uuid` for every clause — they're optional; omit them and the server fills them in. Mint (with `mb uuid`) only the clause you need to reference; never invent, hard-code, or copy a UUID (duplicates are rejected server-side).
-- Keep the options object in slot 1 of every clause — `[op, {options}, ...args]`, id last (`["field", {}, 1779]`). The legacy `["field", id, opts]` order (id second) is rejected pre-flight.
-- 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

@@ -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 —
@@ -11,6 +11,15 @@ when noted: an operator-specific option named in the row, or an explicit `lib/uu
 you mint to reference the clause. Field refs are numeric: `["field", {…}, <field-id>]`.
 Everything here passes `mb query --dry-run`; when in doubt, that loop is the authority.
 
+**Contents**
+
+- [Filter operators](#filter-operators) — Logical, Comparison, Null/empty, String match, Temporal, Segment
+- [Aggregation functions](#aggregation-functions) — including naming and the `offset` window function
+- [Expression operators](#expression-operators) — Arithmetic, Math, String, Temporal, Type conversion, Conditional
+- [References (within clauses)](#references-within-clauses) — field, expression, aggregation
+- [Field option: temporal bucketing](#field-option-temporal-bucketing)
+- [Field option: binning](#field-option-binning)
+
 > For relative date filters, prefer **`time-interval`** / **`relative-time-interval`**
 > (below). `relative-datetime` / `absolute-datetime` literals (e.g. from a UI-built
 > query) also work.
@@ -231,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`

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.