@metabase/cli 0.1.8 → 0.1.10

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

@@ -1,6 +1,6 @@
 ---
 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 …`.
+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, export (with branch guard), 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
 ---
 
@@ -75,25 +75,6 @@ Workflow:
 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
@@ -111,61 +92,26 @@ Pushes Metabase-side changes back to the configured remote. `-m` is the commit m
 
 Workflow:
 
-1. **Branch guard** (below) — confirm the workspace isn't tracking `main`/`master`, or that the user has explicitly accepted exporting to it.
+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.
 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:
+Sync 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.
 
-- 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'`.
+Read the current branch with `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?"
+> "The instance 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.
+> 1. **Create a feature branch** — 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 instance's tracked branch to it; subsequent `git-sync export` calls go to that branch.
+> 2. **Proceed on `main`/`master`** — explicitly accepted.
 
 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
@@ -191,6 +137,5 @@ Use `wait` after `import --no-wait` / `export --no-wait`. Use `cancel-task` if a
 - 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 `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.

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,6 +86,15 @@ 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.
 
+**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`.
 
 ## Where MBQL 5 is consumed
@@ -110,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", {}]] }]
 }
 ```
 
@@ -125,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
@@ -149,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]
 ```

package/skill-data/transform/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 A **transform** persists the result of a query (native SQL or MBQL) to a warehouse table the user can read from cards, dashboards, and other transforms. It runs on a schedule (via `transform-job`) or on-demand (`transform run`).
 
-This skill covers the create-and-run flow. The general flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`). If you're authoring a transform inside a workspace, also load the `workspace` skill for the canonical-vs-isolation-schema rule.
+This skill covers the create-and-run flow. The general flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`).
 
 ## Body shape
 
@@ -53,13 +53,15 @@ mb transform run "$TRANSFORM_ID" --wait --profile <name> --json
 
 Notes:
 
-- `<db-id>` comes from `mb database list --profile <name> --json`. Database ids are per-instance — a workspace child re-numbers them independently of the parent.
-- Target `schema` is the **canonical** name (e.g. `public`). In a workspace, the QP rewrites it to the per-workspace isolation schema (`mb__isolation_<hash>_<ws-id>`) at execution time — don't hard-code that prefix.
+- `<db-id>` comes from `mb database list --profile <name> --json`. Database ids are per-instance.
+- Target `schema` is the schema the result table is written into (e.g. `public`).
 - `--wait` on `transform run` polls until status is `succeeded` or `failed`. Without it you only get `{message: "Transform run started", run_id, final: null}` and have to poll yourself.
-- The `--json` envelope is shape-stable: `{message, run_id, final}`. `final` is always present — `null` when `--wait` is omitted or the run never started, otherwise a full `TransformRun` object with `status` and `message`. On a failed run (`final.status` ∈ {`failed`, `timeout`, `canceled`}) the CLI exits 1 and writes a one-line summary `transform run <id> failed` to stderr; the failure detail lives only in `final.message` on stdout, so `jq -r '.final.message'` is where to look.
+- `--sync` implies `--wait`, then waits until the run's output table is registered — the run registers it itself, no `db sync-schema` needed — adding `target_table_id` to the envelope. Use it when you'll build MBQL on the output (see "Inspect").
+- The `--json` envelope is shape-stable: `{message, run_id, final}` (plus `target_table_id` under `--sync` — a number, or `null` if the table didn't register before the timeout). `final` is always present — `null` when `--wait` is omitted or the run never started, otherwise a full `TransformRun` object with `status` and `message`. On a failed run (`final.status` ∈ {`failed`, `timeout`, `canceled`}) the CLI exits 1 and writes a one-line summary `transform run <id> failed` to stderr; the failure detail lives only in `final.message` on stdout, so `jq -r '.final.message'` is where to look.
 - The heredoc with single-quoted `'EOF'` prevents shell from interpolating any `$vars` inside the SQL.
 - `transform create --json` returns the agent-facing compact projection: `{id, name, description, source_type, target: {type, database, schema, name}, target_db_id}`. Read `target.schema`/`target.name` directly off the create output — no follow-up `transform get` needed to verify where the transform will write.
 - If a transform with the same `name` already has a YAML representation on disk under the configured remote-sync repo, `create` mints a `_2` suffix on the exported filename (the new transform gets a fresh `entity_id`; the prior one isn't touched). For "iterate on the same concept" workflows, prefer `transform update <id>` — see "Iterating on a failing transform" below.
+- **`collection_id` only accepts a collection in the `:transforms` namespace.** Transforms aren't filed next to cards and dashboards — passing a normal analytics collection id (the kind a dashboard lives in) fails create/update with `collection_id: A Transform can only go in Collections in the :transforms namespace.` Omit `collection_id` to leave the transform uncollected (the common case), or create one with `mb collection create --body '{"name":"…"}' --namespace transforms --json` and pass the returned `id`. Cards and dashboards you build **on top of** the transform's output table go in ordinary collections as usual — so "put the transform and its dashboard in collection X" generally means _X holds the dashboard + cards; the transform stays in the transforms namespace._
 
 ## Inspect
 
@@ -68,7 +70,16 @@ mb transform list --profile <name> --json
 mb transform get <id> --profile <name> --full --json     # full transform incl. last run summary
 ```
 
-After a run, the materialized table is queryable via `mb` (`card create` against it, native query against `<schema>.<name>`, etc.). Columns and types are inferred from the result set; if you change the SELECT shape, drop the table first or the next run will fail on a column-mismatch error.
+After a run the table physically exists in the warehouse, but Metabase addresses tables/columns by numeric id, so **MBQL and the UI can't reference a brand-new table until the instance syncs** (native SQL — a native `card` or `mb query` against `<schema>.<name>` — reads it immediately). Run and register in one step with `--sync`:
+
+```bash
+TABLE_ID=$(mb transform run <id> --sync --profile <name> --json | jq -r '.target_table_id')
+mb table get "$TABLE_ID" --include fields --profile <name> --json   # field ids for MBQL
+```
+
+`--sync` runs the transform and polls until its output table is registered, returning the id as `target_table_id` — the run registers the table itself, so no `db sync-schema` is needed. On `target_table_id: null` (still syncing when the poll timed out; exit 0) re-poll `mb transform get <id> --full --json` until the `target_table_id` / `table` linkage lands.
+
+Columns and types are inferred from the result set; change the SELECT shape and the next run fails on a column mismatch — drop the table first (`transform delete-table <id>`). A changed shape also needs a re-run with `--sync` before MBQL sees the new/renamed columns.
 
 ## Inspect runs and cancel an in-flight run
 
@@ -107,10 +118,11 @@ Column "TAGS" not found; SQL statement:
 UPDATE "TRANSFORM" SET "TAGS" = (), "UPDATED_AT" = NOW() WHERE "ID" = ? [42122-214]
 ```
 
-Two specific footguns:
+Three specific footguns:
 
 - **`tags` is not a key on the REST API.** The serdes/YAML representation uses `tags`; the REST contract uses `tag_ids` (an array of integer ids). If you pulled a YAML representation and want to PUT it, translate `tags: [...]` → `tag_ids: [...]` first (or omit it entirely if you're not changing tag membership).
 - **`source_type`, `target_db_id`, `target_table_id`, `entity_id`** are derived/computed by the server. They appear in GET responses for the agent's benefit; the server doesn't accept them on update.
+- **`collection_id` must be a `:transforms`-namespace collection** — a regular card/dashboard collection id is rejected with `A Transform can only go in Collections in the :transforms namespace.` Omit it unless you have one (see the create notes above). Round-tripping the existing value is safe; setting it to an ordinary collection is what fails.
 
 Right shape — patch only what changes:
 
@@ -193,5 +205,4 @@ A schedule lives in a separate resource (`transform-job`) and references one or
 
 - Don't put `transform run` calls in tight polling loops — pass `--wait` and let the CLI handle the polling. Manual loops without `--wait` will hammer the server.
 - Don't author MBQL 4 (the legacy nested `{ type: "query", query: {...} }` shape) by hand — pull a sample with `mb transform get <id> --full --json`. MBQL 5 (`lib/type: "mbql/query"`) **is** authorable by hand thanks to the `mb query --print-schema` + `--dry-run` feedback loop; for non-trivial pipelines you may still prefer building in the UI and exporting.
-- Don't write the workspace isolation schema into `target.schema` or SQL. See the `workspace` skill for the canonical-name rule.
 - Don't paste a `transform get` body into `transform update` — the PUT endpoint only accepts writable keys, and unknown keys (notably `tags`, `source_type`, `entity_id`, `created_at`, `last_run`) leak as raw SQL errors. See "Update body: send only writable keys" above. Use `tag_ids` (not `tags`) on the REST contract.

package/skills/metabase-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: metabase-cli
-description: Drive a Metabase instance from the terminal via the `mb` CLI — auth, databases, cards, dashboards, transforms, queries, search, git-sync, Enterprise workspaces. Discovery entry; load the full guide with `mb skills get core`.
+description: Drive a Metabase instance from the terminal via the `mb` CLI — auth, databases, cards, dashboards, transforms, queries, search, git-sync. Discovery entry; load the full guide with `mb skills get core`.
 allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
 hidden: true
 ---

package/dist/add-collection-DxtuNxeP.mjs

@@ -1,11 +0,0 @@
-import "./command-augment-BH9qgQ5u.mjs";
-import "./error-CTVL5CdB.mjs";
-import "./runtime-B40L_bj8.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import "./render-0_GsapXa.mjs";
-import "./parse-id-D1LTTt9L.mjs";
-import "./poll-task-D8mG49IN.mjs";
-import "./poll-DxpnK1wW.mjs";
-import { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView } from "./add-collection-CwrbKmC1.mjs";
-
-export { add_collection_default as default };

package/dist/auth-B9B4pUaH.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/auth/index.ts
-var auth_default = defineCommand({
-	meta: {
-		name: "auth",
-		description: "Authenticate against a Metabase instance"
-	},
-	default: "login",
-	subCommands: {
-		login: () => import("./login-BJGhZLgZ.mjs").then((m) => m.default),
-		status: () => import("./status-B1dc3bbQ.mjs").then((m) => m.default),
-		list: () => import("./list-BRXGDSMo.mjs").then((m) => m.default),
-		logout: () => import("./logout-BAGLqtnV.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { auth_default as default };

package/dist/capabilities-7e9MgquN.mjs

@@ -1,29 +0,0 @@
-import { z } from "zod";
-
-//#region src/runtime/predicates.ts
-function isPlainObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-//#endregion
-//#region src/output/notice.ts
-function warn(message) {
-	process.stderr.write(message + "\n");
-}
-function listTruncationNotice(bytes) {
-	return `… cut at ${bytes} bytes; rerun with --max-bytes 0`;
-}
-function itemOversizeMessage(bytes, maxBytes) {
-	return `output is ${bytes} bytes, over the ${maxBytes}-byte --max-bytes cap; narrow with --fields, or pass --max-bytes 0 to disable`;
-}
-
-//#endregion
-//#region src/runtime/capabilities.ts
-const Capabilities = z.object({
-	minVersion: z.number(),
-	tokenFeature: z.string().optional()
-});
-const BASELINE_CAPABILITIES = Object.freeze({ minVersion: 58 });
-
-//#endregion
-export { BASELINE_CAPABILITIES, Capabilities, isPlainObject, itemOversizeMessage, listTruncationNotice, warn };

package/dist/card-D54unw6r.mjs

@@ -1,20 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/card/index.ts
-var card_default = defineCommand({
-	meta: {
-		name: "card",
-		description: "Manage Metabase cards (questions, models, metrics)"
-	},
-	subCommands: {
-		list: () => import("./list-Fjjtpghb.mjs").then((mod) => mod.default),
-		get: () => import("./get-CyG_P55z.mjs").then((mod) => mod.default),
-		query: () => import("./query-zWFRDH3T.mjs").then((mod) => mod.default),
-		create: () => import("./create-7JOWFxqu.mjs").then((mod) => mod.default),
-		update: () => import("./update-BsgHRoZ8.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-ZnnJc2iT.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { card_default as default };

package/dist/collection-B5kIKRTL.mjs

@@ -1,20 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/collection/index.ts
-var collection_default = defineCommand({
-	meta: {
-		name: "collection",
-		description: "Manage Metabase collections"
-	},
-	subCommands: {
-		list: () => import("./list-BI1PfPjn.mjs").then((mod) => mod.default),
-		get: () => import("./get-DauAF3sm.mjs").then((mod) => mod.default),
-		items: () => import("./items-BSpapmCU.mjs").then((mod) => mod.default),
-		tree: () => import("./tree-DsnIPFyE.mjs").then((mod) => mod.default),
-		create: () => import("./create-6XE7GYxk.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-BzvqQd34.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { collection_default as default };