@metabase/cli 0.1.4 → 0.1.6

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

@@ -0,0 +1,196 @@
+---
+name: git-sync
+description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections) between an instance and a git remote via `mb git-sync …` — status, dirty / has-remote-changes checks, import (with first-fresh-workspace exception), export (with branch guard + working-tree drift), branches, stash, add/remove a collection from sync. Load when the user wants to "import the latest changes", "export to git", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …`.
+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/*`.
+
+This skill covers the import/export workflow. The general flag conventions and auth setup live in the `core` skill (`mb skills get core`). To author content YAML by hand: the per-resource clause and settings shapes mirror the API form — query bodies follow the `mbql` skill, `visualization_settings` follow the `viz` skill — except the portable YAML uses **name-based** references (e.g. `[Sample Database, PUBLIC, ORDERS, TOTAL]`, and entity-ids for cross-entity FKs) where the API form uses numeric ids. For the on-disk folder layout, model new files on what the synced repo already contains.
+
+## Adding / removing a directory (collection) to sync
+
+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
+
+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 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".
+
+## Import (remote → instance)
+
+```bash
+mb git-sync import --branch <branch> --profile <n>
+# Default flags: --wait, polling --interval 2000 --timeout 600000
+```
+
+Pulls the configured branch and applies it to the instance. Polls until the task reaches a terminal state (`succeeded` / `failed`).
+
+| Flag              | Purpose                                                                              |
+| ----------------- | ------------------------------------------------------------------------------------ |
+| `--branch <name>` | Defaults to the `remote-sync-branch` setting; override per-call.                     |
+| `--no-wait`       | Return as soon as the task is queued; combine with `mb git-sync wait` later.         |
+| `--force`         | **Discards local Metabase-side dirty changes** (lossy). Confirm with the user first. |
+| `--timeout <ms>`  | Polling deadline. Default 600 000.                                                   |
+| `--interval <ms>` | Polling cadence. Default 2 000.                                                      |
+
+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.
+3. `git-sync import --branch <branch>` — runs to terminal status by default.
+
+### First import on a fresh workspace
+
+After `workspace start --repo …` brings up a brand-new workspace, the repo content **must be applied** before any other work — without it the instance has none of the repo content and subsequent edits will diverge from what's on disk.
+
+The container runs a boot-time auto-import on first start, so in most cases the import has already completed by the time `workspace start --wait` returns. Check `git-sync status` first — if `current_task.sync_task_type == "import"` with `status == "successful"` and `.branch` matches the host's branch, you're done; skip the explicit call (it's a wasted round-trip). Only run the explicit `git-sync import` when the auto-import hasn't landed yet.
+
+When you do need the explicit import, the first one on a fresh instance can report `status: conflict` (typically `conflicts: ["Transforms"]`) even when nothing is dirty — the boot-time auto-import sometimes leaves a stale task record that the first explicit import collides with. Retry the same command once; the second call usually succeeds. If it keeps reporting conflict, `git-sync import --force` is safe in this specific case because the workspace is empty — there's no instance-side work for `--force` to discard. (This is a narrow exception to the usual "confirm with the user before `--force`" rule.)
+
+```bash
+HOST_BRANCH=$(git -C <repo-path> symbolic-ref --short HEAD)
+SYNC_STATUS=$(mb git-sync status --profile <ws-name> --json)
+if ! echo "$SYNC_STATUS" | jq -e --arg b "$HOST_BRANCH" \
+     '.current_task.sync_task_type == "import" and .current_task.status == "successful" and (.branch == $b)' >/dev/null; then
+  mb git-sync import --branch "$HOST_BRANCH" --profile <ws-name> --json \
+    || mb git-sync import --branch "$HOST_BRANCH" --profile <ws-name> --json \
+    || mb git-sync import --branch "$HOST_BRANCH" --force --profile <ws-name> --json
+fi
+```
+
+## Export (instance → remote)
+
+```bash
+mb git-sync export -m "commit message" --branch <branch> --profile <n>
+```
+
+Pushes Metabase-side changes back to the configured remote. `-m` is the commit message; without it the server picks a default. Defaults to `--wait`.
+
+| Flag                | Purpose                                                  |
+| ------------------- | -------------------------------------------------------- |
+| `--branch <name>`   | Push to a specific branch instead of the configured one. |
+| `-m, --message <s>` | Commit message.                                          |
+| `--force`           | Force-push / overwrite remote. Confirm with the user.    |
+| `--no-wait`         | Don't poll.                                              |
+
+Workflow:
+
+1. **Branch guard** (below) — confirm the workspace 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.
+3. `git-sync export -m "..."` — pushes and polls.
+4. (Optional) `git-sync status` — verify `dirty: false` after.
+5. **Working-tree drift** (below) — if this is a `--repo` bind-mount workspace, the host repo's working tree + index will lag behind the new HEAD. Surface this and offer to realign.
+
+### Branch guard: don't export to main/master without confirmation
+
+Workspace work is conventionally done on a feature branch — exporting to `main` (or `master`) commits team-shared content directly. Before `git-sync export`, check the tracked branch and if it's `main`/`master`, ask the user whether to switch first.
+
+Reading the current branch:
+
+- For a `--repo` bind-mount workspace, `git -C <repo-path> symbolic-ref --short HEAD` is the most reliable read — that's what the workspace's `remote-sync-branch` was bound to at start time.
+- Otherwise: `mb git-sync status --profile <n> --json | jq -r '.branch'`.
+
+If the branch is `main` or `master`, prompt with `AskUserQuestion`:
+
+> "The workspace is tracking `<branch>` — exporting commits straight to it. Switch to a feature branch first?"
+>
+> 1. **Create a feature branch via the workspace** — agent suggests a name (e.g., `agent/<task>`); run `mb git-sync create-branch <name> --profile <n>`. This exports current dirty state to the new branch and switches the workspace's tracked branch to it; subsequent `git-sync export` calls go to that branch.
+> 2. **Switch the host's branch first (bind-mount workspaces)** — `git -C <repo> checkout -b <name>` on the host, then pass `--branch <name>` on the next `git-sync export` so the export targets the new branch (the workspace's `remote-sync-branch` setting won't auto-update from a host-side checkout).
+> 3. **Proceed on `main`/`master`** — explicitly accepted; surface the resulting commit (`git -C <repo> log --oneline -1`) afterwards so the user can amend or revert.
+
+Skip the prompt only if the user's instructions already specified the branch (e.g., they explicitly said "export to main" or named a feature branch). Don't silently default to whatever `remote-sync-branch` happens to point at.
+
+### Post-export: working-tree drift on `--repo` bind-mount workspaces
+
+When the workspace exports against a host bind mount, the in-container serializer writes the new commit object directly into the bind-mounted `.git/` (creating tree/blob objects and advancing the branch ref) but **does not update the host's working tree or index**. After a successful export, the host repo state is:
+
+- HEAD: the new export commit.
+- Index: still matches the _previous_ HEAD (whatever the user had staged before).
+- Working tree: still matches the _previous_ HEAD.
+
+`git status` then shows "Changes to be committed" that look like the export's content reverting back — purely a display artifact, not an actual revert. The container does this on purpose to avoid clobbering work-in-progress on the host. **Realigning is _applying_ the new HEAD's content to your worktree, not discarding work** — the new commit was written by the exporter, not by your local edits, and your tree/index are stale relative to the new HEAD until you realign.
+
+**Surface this to the user** after an export against a `--repo` workspace — don't leave them staring at a confusing `git status`. Offer to realign.
+
+**Prefer `git restore` over `git reset --hard`.** When the only "changes" are the drift artifact (no real local edits), `git restore` does the same job and isn't classified as a destructive operation by Claude Code's permission system — `git reset --hard` is, and gets blocked even after a user-confirmation dialog:
+
+```bash
+git -C <repo> restore --staged --worktree .   # non-destructive; aligns index + working tree to HEAD
+```
+
+This is the right default after a `git-sync export` realignment when the user had nothing else staged. If `git status` shows a mix of drift artifacts and real pending work, fall back to the stash sequence:
+
+```bash
+git -C <repo> stash --include-untracked
+git -C <repo> restore --staged --worktree .
+git -C <repo> stash pop
+```
+
+`git reset --hard HEAD` is the canonical equivalent and still valid — but **confirm with the user** before running it, and expect Claude Code to gate it as destructive even after the dialog. `git restore --staged --worktree .` produces the same end-state with less friction.
+
+Or pull in the new files selectively with `git -C <repo> checkout HEAD -- <path>`. Quick check that this is what you're seeing: `git -C <repo> diff --cached HEAD~1 --stat` returns empty (the index matches the parent commit, not the new HEAD).
+
+## Branches
+
+```bash
+mb git-sync branches --profile <n> --json                 # list remote branches
+mb git-sync create-branch <name> --profile <n>            # create + switch sync to it
+mb git-sync stash --profile <n>                           # export current state to a NEW branch
+```
+
+`stash` is the safe move when the instance has team work you don't want to lose, but you need to pivot to a different branch (`import` would discard, `export --force` would overwrite). It exports current state to a fresh branch first.
+
+## Polling and cancelling
+
+```bash
+mb git-sync wait --profile <n>             # block on the in-flight task
+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.
+
+## 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.
+- Don't drive `git-sync` against a Metabase instance that doesn't have remote-sync configured — every verb returns an error pointing at the missing `remote-sync-*` settings. To check: `mb setting get remote-sync-url --profile <n> --json`.
+- 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 — workspace work is conventionally on a feature branch. See "Branch guard" above.
+- Don't pretend the host's `git status` is clean after `git-sync export` against a `--repo` bind mount — the export advances HEAD but leaves the working tree + index behind. See "Working-tree drift" 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.

package/skill-data/mbql/SKILL.md

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

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

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