@metabase/cli 0.1.8-alpha.drop-workspaces.75fe1d5 → 0.1.9

package/dist/{update-YxMDkgY6.mjs → update-CilTW98H.mjs}

@@ -1,13 +1,13 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand } from "./runtime-DHJQOqZu.mjs";
-import { renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand } from "./runtime-Ck8KKQe-.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
 import "./input-xewHccej.mjs";
-import { parseId } from "./parse-id-sz7USsM2.mjs";
-import { readBody } from "./body-CibAG3Gn.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
+import { readBody } from "./body-2jl-YSxT.mjs";
 import { bodyInputFlags } from "./body-flags-D78h_-Ua.mjs";
-import "./validate-CqVB_3_p.mjs";
-import { MEASURE_DEFINITION_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-BUTNK00f.mjs";
+import "./validate-B62TRDGV.mjs";
+import { MEASURE_DEFINITION_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-BpiN1CFu.mjs";
 import { Measure, MeasureUpdateInput, measureView } from "./measure-ClESGxIb.mjs";
 
 //#region src/commands/measure/update.ts

package/dist/{update-BA0wgxkx.mjs → update-CoVvsU-I.mjs}

@@ -1,10 +1,10 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand } from "./runtime-DHJQOqZu.mjs";
-import { renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand } from "./runtime-Ck8KKQe-.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
 import "./input-xewHccej.mjs";
-import { parseId } from "./parse-id-sz7USsM2.mjs";
-import { readBody } from "./body-CibAG3Gn.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
+import { readBody } from "./body-2jl-YSxT.mjs";
 import { bodyInputFlags } from "./body-flags-D78h_-Ua.mjs";
 import { TransformJob, TransformJobUpdateInput, transformJobView } from "./transform-job-DpDGoqQt.mjs";
 

package/dist/{update-DWwBv7XP.mjs → update-DBN7yfAk.mjs}

@@ -1,11 +1,11 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand } from "./runtime-DHJQOqZu.mjs";
-import { renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand } from "./runtime-Ck8KKQe-.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
 import "./input-xewHccej.mjs";
 import "./field-MGxpNQUH.mjs";
-import { parseId } from "./parse-id-sz7USsM2.mjs";
-import { readBody } from "./body-CibAG3Gn.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
+import { readBody } from "./body-2jl-YSxT.mjs";
 import { bodyInputFlags } from "./body-flags-D78h_-Ua.mjs";
 import { Table, TableUpdateInput, tableView } from "./table-CkWja2UH.mjs";
 

package/dist/{update-D5fs9raK.mjs → update-DqSG5_Ie.mjs}

@@ -1,13 +1,13 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand } from "./runtime-DHJQOqZu.mjs";
-import { renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand } from "./runtime-Ck8KKQe-.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
 import "./input-xewHccej.mjs";
-import { parseId } from "./parse-id-sz7USsM2.mjs";
-import { readBody } from "./body-CibAG3Gn.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
+import { readBody } from "./body-2jl-YSxT.mjs";
 import { bodyInputFlags } from "./body-flags-D78h_-Ua.mjs";
-import "./validate-CqVB_3_p.mjs";
-import { SEGMENT_DEFINITION_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-BUTNK00f.mjs";
+import "./validate-B62TRDGV.mjs";
+import { SEGMENT_DEFINITION_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-BpiN1CFu.mjs";
 import { Segment, SegmentUpdateInput, segmentView } from "./segment-Be2v4ilr.mjs";
 
 //#region src/commands/segment/update.ts

package/dist/{update-DdI9epnQ.mjs → update-DykqQLfo.mjs}

@@ -1,15 +1,15 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand } from "./runtime-DHJQOqZu.mjs";
-import { renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand } from "./runtime-Ck8KKQe-.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
 import "./input-xewHccej.mjs";
 import "./field-MGxpNQUH.mjs";
-import { Card, CardUpdateInput, cardView } from "./card-BtPiKjbB.mjs";
-import { parseId } from "./parse-id-sz7USsM2.mjs";
-import { readBody } from "./body-CibAG3Gn.mjs";
+import { Card, CardUpdateInput, cardView } from "./card-DnIeMmUn.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
+import { readBody } from "./body-2jl-YSxT.mjs";
 import { bodyInputFlags } from "./body-flags-D78h_-Ua.mjs";
-import "./validate-CqVB_3_p.mjs";
-import { CARD_DATASET_QUERY_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-BUTNK00f.mjs";
+import "./validate-B62TRDGV.mjs";
+import { CARD_DATASET_QUERY_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-BpiN1CFu.mjs";
 
 //#region src/commands/card/update.ts
 var update_default = defineMetabaseCommand({

package/dist/{update-dashcard-BA65Gjah.mjs → update-dashcard-DZ8oV8up.mjs}

@@ -1,10 +1,10 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand } from "./runtime-DHJQOqZu.mjs";
-import { renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand } from "./runtime-Ck8KKQe-.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
 import "./input-xewHccej.mjs";
-import { parseId } from "./parse-id-sz7USsM2.mjs";
-import { readBody } from "./body-CibAG3Gn.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
+import { readBody } from "./body-2jl-YSxT.mjs";
 import { bodyInputFlags } from "./body-flags-D78h_-Ua.mjs";
 import { DashboardDetail, Dashcard, DashcardPatchInput, dashcardView } from "./dashboard-FY5UzJ_Z.mjs";
 

package/dist/{upgrade-82Zo6-n6.mjs → upgrade-B8sEEQdQ.mjs}

@@ -1,7 +1,7 @@
 import { AbortError, NetworkError, TimeoutError, UnknownError, errorMessage, isNotFoundError } from "./command-augment-BH9qgQ5u.mjs";
-import { outputFlags, package_default } from "./error-BYn4eqJH.mjs";
-import { HttpError, USER_AGENT, combineAborts, defineMetabaseCommand, parseJson, throwIfAborted } from "./runtime-DHJQOqZu.mjs";
-import { renderItem, writeText } from "./capabilities-Dj3NgPHg.mjs";
+import { outputFlags, package_default } from "./error-BndUmcwS.mjs";
+import { HttpError, USER_AGENT, combineAborts, defineMetabaseCommand, parseJson, throwIfAborted } from "./runtime-Ck8KKQe-.mjs";
+import { renderItem, writeText } from "./capabilities-7L9GVMd_.mjs";
 import { promptConfirm } from "./prompt-u4WhE4T5.mjs";
 import { z } from "zod";
 import { realpathSync } from "node:fs";

package/dist/{uuid-B2xU0Ibp.mjs → uuid-lLVnEoBN.mjs}

@@ -1,7 +1,7 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { outputFlags } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand, parseInteger } from "./runtime-DHJQOqZu.mjs";
-import { writeJson, writeText } from "./capabilities-Dj3NgPHg.mjs";
+import { outputFlags } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand, parseInteger } from "./runtime-Ck8KKQe-.mjs";
+import { writeJson, writeText } from "./capabilities-7L9GVMd_.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 

package/dist/{validate-CqVB_3_p.mjs → validate-B62TRDGV.mjs}

@@ -1,5 +1,5 @@
 import { ConfigError, escapeJsonPointerSegment } from "./command-augment-BH9qgQ5u.mjs";
-import { isPlainObject } from "./capabilities-Dj3NgPHg.mjs";
+import { isPlainObject } from "./capabilities-7L9GVMd_.mjs";
 import { z } from "zod";
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";

package/dist/{validate-query-BUTNK00f.mjs → validate-query-BpiN1CFu.mjs}

@@ -1,6 +1,6 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { writeJson } from "./capabilities-Dj3NgPHg.mjs";
-import { assertNotLegacyEnvelopeWrappingMbql5, isMbql5Query, validateQuery } from "./validate-CqVB_3_p.mjs";
+import { writeJson } from "./capabilities-7L9GVMd_.mjs";
+import { assertNotLegacyEnvelopeWrappingMbql5, isMbql5Query, validateQuery } from "./validate-B62TRDGV.mjs";
 
 //#region src/commands/validate-query.ts
 const skipValidateFlag = { "skip-validate": {

package/dist/{values-Cs6sJEid.mjs → values-oD72EtRq.mjs}

@@ -1,9 +1,9 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand } from "./runtime-DHJQOqZu.mjs";
-import { formatScalar, renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand } from "./runtime-Ck8KKQe-.mjs";
+import { formatScalar, renderSummary } from "./capabilities-7L9GVMd_.mjs";
 import { FieldValues, fieldValuesView } from "./field-MGxpNQUH.mjs";
-import { parseId } from "./parse-id-sz7USsM2.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
 
 //#region src/commands/field/values.ts
 var values_default = defineMetabaseCommand({

package/dist/{verify-D8wLpHse.mjs → verify-Bg6F0oFN.mjs}

@@ -1,5 +1,5 @@
 import { MetabaseError, NetworkError, TimeoutError, errorMessage } from "./command-augment-BH9qgQ5u.mjs";
-import { HttpError, createClient, probeServer } from "./runtime-DHJQOqZu.mjs";
+import { HttpError, createClient, probeServer } from "./runtime-Ck8KKQe-.mjs";
 import { z } from "zod";
 
 //#region src/domain/user.ts

package/dist/{wait-CW6jJWmY.mjs → wait-BtzuqQC3.mjs}

@@ -1,10 +1,10 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-BYn4eqJH.mjs";
-import { defineMetabaseCommand } from "./runtime-DHJQOqZu.mjs";
-import { renderSummary } from "./capabilities-Dj3NgPHg.mjs";
-import { parseId } from "./parse-id-sz7USsM2.mjs";
-import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-DnzX7GX_.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DO11tBiL.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BndUmcwS.mjs";
+import { defineMetabaseCommand } from "./runtime-Ck8KKQe-.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-BMjCkDaj.mjs";
+import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-CiRA0ER9.mjs";
 
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;

package/dist/{wait-flags-Dl-xi5yx.mjs → wait-flags-DyFfZeav.mjs}

@@ -1,5 +1,5 @@
-import { parseId } from "./parse-id-sz7USsM2.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DO11tBiL.mjs";
+import { parseId } from "./parse-id-Boqc4wn4.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-BMjCkDaj.mjs";
 
 //#region src/commands/wait-flags.ts
 const waitScheduleFlags = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metabase/cli",
-  "version": "0.1.8-alpha.drop-workspaces.75fe1d5",
+  "version": "0.1.9",
   "description": "Metabase CLI",
   "license": "AGPL-3.0",
   "repository": {

package/skill-data/core/SKILL.md

@@ -15,7 +15,7 @@ auth | db | table | field | query | card | dashboard | snippet | segment | measu
 transform | transform-job | setting | search | git-sync | setup | eid | uuid | upgrade | skills
 ```
 
-The patterns below — auth, flag conventions, output flags, body input — apply across **every** group. Per-command flags, examples, and output schemas live in `mb __manifest` (see below). A few flows have their own specialized skills; load them on demand (see "Specialized skills"). Authoring any query body (cards, transforms, measures, segments, ad-hoc `mb query`) is one — load `mbql` whenever you build MBQL by hand.
+The patterns below — auth, flag conventions, output flags, body input — apply across **every** group. Per-command flags, examples, and output schemas live in `mb __manifest` (see below). A few flows have their own specialized skills; load them on demand (see "Specialized skills"). Authoring any query body (cards, transforms, measures, segments, ad-hoc `mb query`) is one — load `mbql` whenever you build MBQL by hand. When a **question** (card) needs a query, prefer MBQL over native SQL — it's portable across warehouse engines and the CLI pre-flight-validates it. Try it first, but don't force it: fall back to native SQL when MBQL can't express the query, or when an MBQL body keeps failing server-side and you can't resolve it.
 
 ## Auth & profiles
 
@@ -128,19 +128,19 @@ Use it to (a) enumerate verbs, (b) validate flag names before constructing a com
 
 Routine verb shapes (list / get / create / update), every flag, and output JSON Schemas live in `mb __manifest` — pull them on demand. Below is only what the manifest does _not_ tell you: the footguns and non-obvious behaviors.
 
-- **db traversal vs. rollup.** Default to granular: `database list` → `database schemas <db-id>` → `database schema-tables <db-id> <schema>` → `table get <table-id> --include fields`. The rollup endpoints (`database get --include tables.fields`, `database metadata <db-id>`) pull megabytes and blow the context window on any real warehouse — use them only on a small/dev db. `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately.
+- **db traversal vs. rollup.** Default to granular: `database list` → `database schemas <db-id>` → `database schema-tables <db-id> <schema>` → `table get <table-id> --include fields`. The rollup endpoints (`database get --include tables.fields`, `database metadata <db-id>`) pull megabytes and blow the context window on any real warehouse — use them only on a small/dev db. `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
 - **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact) or use `table fields <id>` (list envelope). `table metadata <id>` adds FKs + dimensions (heavier). `table update` patches table-level metadata only; physical columns aren't editable here.
 - **field has no `list`.** Fields are per-table — get them via `table get <id> --include fields`. Never enumerate fields across a whole db (context blow-up). `field summary` is live cardinality `{field_id, count, distincts}`; `field values` is the cached distinct set (`has_more_values: true` ⇒ truncated cache). `field update` patches metadata only; `base_type` isn't editable.
 - **card.** `dataset_query` is the **flat** `mbql/query` value, not a legacy `{type:"query",query:…}` envelope (→ `mbql` skill). `--export-format csv|xlsx` streams the raw export (pipe to a file), bypassing the JSON envelope. `archive` is the only delete; unarchive with `update --body '{"archived":false}'`. `visualization_settings` keys are scoped by `display` and aren't pre-flighted — see the `viz` skill.
-- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; use negative ids for new cards). `create` accepts the **same** `dashcards` array in its initial body, so you can lay out the whole dashboard in one call — negative ids for new cards, and `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create`/`update` pre-flight every positive `card_id` against live server state and exit **2** with `{ok:false,errors:[…]}` on a bad ref — non-bypassable (no `--skip-validate`). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them.
+- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; use negative ids for new cards). `create` accepts the **same** `dashcards` array in its initial body, so you can lay out the whole dashboard in one call — negative ids for new cards, and `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create`/`update` pre-flight every positive `card_id` against live server state and exit **2** with `{ok:false,errors:[…]}` on a bad ref — non-bypassable (no `--skip-validate`). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **Dashcard geometry: the grid is 24 columns wide.** Each dashcard's `{col, row, size_x, size_y}` is in grid units — `col` (0-indexed, left edge) and `size_x` are columns, `row`/`size_y` are rows; **full-width is `size_x: 24`** (`size_x: 12` is half a row — the usual cause of a card that only fills half the width, since it's a common per-chart default). Keep `col + size_x ≤ 24`, start each card's `col` at 0 for a full-width stack, and don't overlap cards (the server stores whatever you send — it won't auto-fix collisions).
 - **snippet `--archived` is a swap, not a union** — list returns _either_ active _or_ archived rows, never both. (Same shape for `--filter archived` on dashboard/collection.)
 - **segment / measure** `update` and `archive` require a non-blank `revision_message` (audit-logged); the CLI does not synthesize it on `update`. `archive` defaults to `"Archived via mb CLI"` — override with `--revision-message`. `definition` is a flat MBQL clause (→ `mbql` skill): segment = a filter, measure = exactly one aggregation.
 - **collection `<ref>`** accepts four forms only — positive int, `root`, `trash`, or a 21-char entity_id — anything else is a client-side `ConfigError`. `collection items` auto-paginates (cap with `--limit`, which then omits `total`). `collection tree` is **JSON-only** — `--format text` is rejected.
 - **setting set** parses the value as **strict JSON**: a string is `'"value"'` (inner quotes), booleans `true`/`false`, numbers bare. Wrong quoting silently errors — confirm with `setting get <key>` after. `setting get --json` works on every value type (it wraps bare-text responses into `{key, value}`).
 - **search vs. list.** For plain enumeration of cards/dashboards/collections use the dedicated `… list` verbs; reach for `search --models <kind>` only for ranking against a query string or a cross-resource lookup.
-- **transform.** Iterate with `transform update <id>`, never `delete` + `create` — keeps the row, `entity_id`, materialized table, and YAML filename (avoids `_2` suffixes and noisy git history). `transform run` needs `--wait` or you get only `{run_id, final:null}`. (→ `transform` skill.)
+- **transform.** Iterate with `transform update <id>`, never `delete` + `create` — keeps the row, `entity_id`, materialized table, and YAML filename (avoids `_2` suffixes and noisy git history). `transform run` needs `--wait` (or `--sync`, which also waits for the run's output table to register and returns `target_table_id`) or you get only `{run_id, final:null}`. (→ `transform` skill.)
 - **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only — it errors against an already-configured one. Mostly for bootstrapping local / e2e instances.
-- **eid** translates a string entity id → numeric id: `mb eid --model <model> <eid1,eid2> --json` (EIDs are a positional used with `--model`; or pass `--body '{"entity_ids":{"card":["…"]}}'`). Useful when an external system hands you an entity id and a verb needs the numeric one.
+- **eid** translates a string entity id → numeric id: `mb eid --model <model> <eid1,eid2> --json` (EIDs are a positional used with `--model`; or pass `--body '{"entity_ids":{"card":["…"]}}'`). Entity ids are NanoIDs that can start with `-`, which the positional form misreads as a flag (shell quotes don't help — the `-` survives into argv). For an id that may start with `-`, use `--body` — the id is a JSON string value, immune to flag parsing: `mb eid --body '{"entity_ids":{"card":["-…"]}}'`. Useful when an external system hands you an entity id and a verb needs the numeric one.
 - **query / uuid.** `mb query` is the ad-hoc MBQL surface (`--print-schema` → `--dry-run` → run); `mb uuid --count <n>` mints the `lib/uuid` values every MBQL 5 clause needs. Both workflows live in the `mbql` skill.
 
 ## Specialized skills (load on demand)

package/skill-data/mbql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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, when lib/uuid is needed (it's optional — only to reference a clause), 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, joins and FK traversal, multi-stage pipelines, 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", "join two tables", "month-over-month", or any `--dry-run` / `mb query` work.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 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.
+Prefer MBQL over native SQL: it's portable across warehouse engines and the CLI pre-flight-validates it. Try it first, but don't force it — 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.
 
 The general flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`).
 
@@ -24,8 +24,8 @@ A query is a flat object — `lib/type`, a numeric `database` id, and an ordered
     {
       "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]]
+      "aggregation": [["count", {}]],
+      "breakout": [["field", { "temporal-unit": "month" }, 22]]
     }
   ]
 }
@@ -33,43 +33,42 @@ A query is a flat object — `lib/type`, a numeric `database` id, and an ordered
 
 - **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.
+- `source-card` references a saved card by its **numeric id** (from `mb card list`), not its string 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]]
+["field", { "base-type": "type/Text" }, 1779]   // field id is THIRD; options may be empty {}
+["count", {}]                                    // no args
+["sum",   {}, ["field", {}, 42]]
+["=",     {}, ["field", {}, 1779], "delivered"]
+["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 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
+## UUIDs: optional — mint only to reference a clause
 
-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.
+`lib/uuid` is **optional — leave it out whenever you can.** Omit it and the server generates a unique one for every clause as the query comes in; an empty options object `{}` is the normal, preferred case. Don't add a UUID per clause: it's needless work, and the more UUIDs you hand-manage the easier it is to trip the server's "all `lib/uuid`s must be unique" check — a duplicated UUID passes pre-flight, then fails server-side.
 
-```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.
+Set an explicit `lib/uuid` only when you must **reference a clause from elsewhere in the query** — the one thing the server can't do for you, since you have to know the value to point at. The case that needs it: **ordering by (or otherwise reusing) an aggregation.** `["aggregation", {…}, "<uuid>"]`'s third arg is the **string** `lib/uuid` of the target aggregation, so give that aggregation an explicit `lib/uuid` and point the ref at the same string. A numeric position fails with `must be the target aggregation's lib/uuid (string), not a numeric position`.
 
 ```json
 "aggregation": [["count", { "lib/uuid": "AGG_UUID" }]],
-"order-by":   [["desc", { "lib/uuid": "ORDER_UUID" },
-                 ["aggregation", { "lib/uuid": "REF_UUID" }, "AGG_UUID"]]]
+"order-by":   [["desc", {}, ["aggregation", {}, "AGG_UUID"]]]
 ```
 
-(`AGG_UUID` appears twice and must be the _same_ minted value; `ORDER_UUID` and `REF_UUID` are distinct.)
+(`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`.)
+
+On the rare occasion you do need one, **always mint it with `mb uuid` — never write, guess, or copy a UUID yourself.** A hand-authored value is either 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 happens to look valid, risks colliding with another clause. Only `mb uuid`gives you genuine, unique v4s — mint just the few you reference (this 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
+```
 
 ## Authoring loop: print-schema → dry-run → run
 
@@ -87,7 +86,14 @@ mb query --file q.json --profile <n> --json                     # 3. validate +
 
 `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.
 
-A successful run emits the **full `/api/dataset` envelope** — `data.rows`, `data.cols`, plus heavy `data.results_metadata` and per-column fingerprints. For ad-hoc exploration project `--fields data.rows` (add `data.cols` if you need column names); without it even a few rows render as hundreds of lines of metadata. (`mb query` also runs a **native** body — `{database, type:"native", native:{query:"SELECT …"}}` — which skips pre-flight and is the quickest way to eyeball raw warehouse data; same `--fields data.rows` advice applies.)
+**Pre-flight is a lightweight shape check, not the full backend validator.** It checks JSON shape, `lib/uuid` format, and enum values — not operator names, the first-stage source rule, or whether a reference resolves. A clean `--dry-run` is necessary but not sufficient: a body can pass pre-flight and still fail on the server (exit `1`). The Metabase server is the authority — when a run fails, read its error and fix the body. The common ones and what they mean:
+
+- `not a known MBQL clause` → a misspelled or unsupported **operator**. Check the vocabulary in `operators.md` (`mb skills get mbql --full`).
+- `Initial MBQL stage must have either :source-table or :source-card` → the **first stage** is missing its source (a numeric table or card id); only the first stage takes one, later stages read the previous stage's columns.
+- `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.
 
 `--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`.
 
@@ -112,7 +118,7 @@ The most common mistake. The legacy MBQL 4 shape `{ "type": "query", "database":
   "lib/type": "mbql/query",
   "database": 2,
   "stages": [{ "lib/type": "mbql.stage/mbql", "source-table": 190,
-               "aggregation": [["count", { "lib/uuid": "<mint>" }]] }]
+               "aggregation": [["count", {}]] }]
 }
 ```
 
@@ -127,15 +133,74 @@ Anything that is not `lib/type: "mbql/query"` is sent as-is and normalized serve
 
 `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`.
 
+## Joins and FK traversal
+
+Two ways to read columns from a related table.
+
+**Explicit join.** A stage's `joins` array holds join objects, each with three required keys: `stages` (the joined source as its own one-stage array carrying `source-table`/`source-card`), `conditions` (the ON clause — `[op, {}, leftRef, rightRef]`, slot-1 rule and all), and `alias` (the string name you address joined columns by). Optional `strategy` (`left-join` default; also `right-join` / `inner-join` / `full-join`) and `fields` (`"all"` | `"none"` | an array of refs — which joined columns to select). Reference a joined column anywhere downstream by putting **`join-alias`** in the field options:
+
+```json
+"joins": [
+  {
+    "alias": "Customers",
+    "strategy": "left-join",
+    "stages": [{ "lib/type": "mbql.stage/mbql", "source-table": 170 }],
+    "conditions": [
+      ["=", {}, ["field", {}, 1711], ["field", { "join-alias": "Customers" }, 1684]]
+    ],
+    "fields": "none"
+  }
+],
+"breakout": [["field", { "join-alias": "Customers" }, 1682]]
+```
+
+The condition's left ref is a column of the stage's own source (`1711` = orders.customer_id); the right ref carries `join-alias` and points at the joined table's key (`1684` = customers.id). Every later reference to a joined column (`1682` = customers.plan) needs that same `join-alias`. Stack multiple objects in `joins` for multiple joins, each with its own `alias`.
+
+**Implicit FK join via `source-field`.** For a single-hop FK lookup, skip the join — put the FK column's id in the target field's `source-field` option and Metabase traverses the relationship:
+
+```json
+["field", { "source-field": 1711 }, 1682] // orders.customer_id → customers.plan
+```
+
+`source-field` is the **FK field id** (orders.customer_id); the third element is the **target field id** in the related table (customers.plan). Use it for "show a column from the table this FK points at"; reach for an explicit join when you need a non-FK condition, a non-default strategy, or control over which joined columns return.
+
+## Multi-stage pipelines
+
+Stages run in order; each reads the **previous stage's output columns** — the breakouts and aggregations it produced — referenced by **string name + `base-type`**, not a numeric field id. Only the first stage takes a `source-table`/`source-card`. The reason to add a stage is to operate on an aggregate (you can't filter or order by an aggregation within the stage that computes it): aggregate, then filter the aggregate, then order + limit.
+
+```json
+"stages": [
+  { "lib/type": "mbql.stage/mbql", "source-table": 175,
+    "aggregation": [["sum", { "name": "total" }, ["field", {}, 1715]]],
+    "breakout": [["field", {}, 1711]] },
+  { "lib/type": "mbql.stage/mbql",
+    "filters": [[">", {}, ["field", { "base-type": "type/BigInteger" }, "total"], 0]] },
+  { "lib/type": "mbql.stage/mbql",
+    "order-by": [["desc", {}, ["field", { "base-type": "type/BigInteger" }, "total"]]],
+    "limit": 3 }
+]
+```
+
+Later stages address the first stage's aggregation by the `name` you gave it (`"total"`) — set that `name`, or the column lands as the default `sum` / `count` / … and you reference that string instead.
+
+**Window functions** sit in `aggregation` next to ordinary aggregates. `offset` reads a value from another breakout row — month-over-month is `offset` of a sum by `-1` against a monthly breakout:
+
+```json
+"aggregation": [
+  ["sum", { "name": "revenue" }, ["field", {}, 1715]],
+  ["offset", { "name": "prev_month" }, ["sum", {}, ["field", {}, 1715]], -1]
+],
+"breakout": [["field", { "temporal-unit": "month" }, 1717]]
+```
+
+**Binning** is a breakout-level field option — bucket a numeric column into ranges with `["field", { "binning": { "strategy": "num-bins", "num-bins": 5 } }, 1715]`, the numeric counterpart to the `temporal-unit` bucket. Strategies (`num-bins` / `bin-width` / `default`) are in the operator reference.
+
 ## 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" }
-]
+["count", { "name": "shipments_shipped", "display-name": "Shipments shipped" }]
 ```
 
 ## Operator reference
@@ -151,7 +216,7 @@ mb skills path mbql           # → the skill dir; then Read references/operator
 
 ## Don't
 
-- Don't invent, hard-code, or copy `lib/uuid` values — `mb uuid` every slot at author time.
+- 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).
 - 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`.

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

@@ -5,15 +5,15 @@ form. The clause _structure_ and the slot-1-options rule are in the SKILL.md bod
 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.
+abbreviates the slot-1 options object — usually empty (`{}`), since `lib/uuid` is
+optional and the server generates it (see the SKILL body). It carries a value only
+when noted: an operator-specific option named in the row, or an explicit `lib/uuid`
+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.
 
-> 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.
+> 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.
 
 ---
 
@@ -67,7 +67,7 @@ options object.
 | `ends-with`        | field, 1+ strings |
 
 ```json
-["contains", { "lib/uuid": "<mint>", "case-sensitive": false }, ["field", {…}, 9], "widget"]
+["contains", { "case-sensitive": false }, ["field", {…}, 9], "widget"]
 ```
 
 ### Temporal
@@ -120,7 +120,7 @@ A stage's `aggregation` is a list of aggregation clauses.
 ```
 
 **Naming** — set `name` (warehouse column) and/or `display-name` (UI header) in the
-options object: `["sum", { "lib/uuid": "<mint>", "name": "revenue", "display-name": "Revenue" }, …]`.
+options object: `["sum", { "name": "revenue", "display-name": "Revenue" }, …]`.
 
 **Window function** — `offset` is only valid inside `aggregation`:
 
@@ -205,7 +205,7 @@ Add/subtract/interval units: `year`, `quarter`, `month`, `week`, `day`, `hour`,
 | `coalesce` | 2+ expressions                 | first non-null                                       |
 
 ```json
-["case", { "lib/uuid": "<mint>", "lib/expression-name": "Tier" },
+["case", { "lib/expression-name": "Tier" },
   [[[">", {…}, ["field", {…}, 14], 100], "Premium"],
    [["<=", {…}, ["field", {…}, 14], 20], "Budget"]],
   "Standard"]
@@ -235,7 +235,7 @@ positional arg is the default.)
   `month-of-year`, `quarter-of-year`, `year-of-era`, `second-of-minute`.
 
 ```json
-["field", { "lib/uuid": "<mint>", "temporal-unit": "month" }, 22]
+["field", { "temporal-unit": "month" }, 22]
 ```
 
 ## Field option: binning
@@ -249,5 +249,5 @@ positional arg is the default.)
 | `default`   | —                    | Metabase chooses                 |
 
 ```json
-["field", { "lib/uuid": "<mint>", "binning": { "strategy": "num-bins", "num-bins": 10 } }, 14]
+["field", { "binning": { "strategy": "num-bins", "num-bins": 10 } }, 14]
 ```