@metabase/cli 0.1.2 → 0.1.4-alpha.skill-packaging.1c8ec40

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, also load the `metabase-representation-format` skill — it covers the file-tree layout and per-resource YAML shape.
+
+## 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/transform/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: transform
+description: Author and run Metabase transforms via `mb` — body shape (native SQL + MBQL 5), create + run-with-wait, run inspection, cancel, the `update`-vs-recreate iteration rule, and the writable-keys-only PATCH contract. Load when the user touches transforms — "create a transform", "run a transform", "fix a failing transform", "list transform runs", "cancel a running transform", or anything `mb transform …`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Transforms
+
+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.
+
+## Body shape
+
+A transform has two halves:
+
+- `source` — the query to run (`type: "query"`, with `query.type` of `native` or `mbql`).
+- `target` — the warehouse destination (`type: "table"`, with `database`, `schema`, `name`).
+
+Native SQL is the simplest source and the easiest to author by hand. MBQL is what the Metabase UI emits and is much more verbose; pull a sample with `mb transform get <id> --full --json` if you need its shape.
+
+If `source.query` is **MBQL 5** (`lib/type: "mbql/query"`), `transform create` and `transform update` validate it against the bundled query schema before sending; failure exits 2 with `{ ok, errors: [{path, message}] }` on stdout. To author MBQL 5 by hand: fetch the schema via `mb query --print-schema --profile <n>`, iterate the body with `mb query --file q.json --dry-run --profile <n>` until `ok: true`, then drop it into `source.query`. Legacy MBQL 4 and native sources skip pre-flight. Pass `--skip-validate` to bypass the pre-flight and let the server be the authority — useful when the bundled schema disagrees with what the server actually accepts.
+
+**Mint UUIDs for `lib/uuid` slots before assembling the body — never invent, hard-code, or reuse them.** Every clause options object carries a `lib/uuid` (UUID v4); the bundled schema enforces RFC 4122 format strictly, so placeholder strings fail `--dry-run`. Workflow: count the slots, run `mb uuid --count <N> --json`, substitute each minted value into its slot. The examples below use `<UUID:label>` sentinels (NOT valid UUIDs) so the assembly step is unambiguous — replace each sentinel with a freshly-minted UUID before sending. Same `<UUID:label>` token must be replaced with the same minted UUID (used for aggregation-ref ↔ aggregation pairing); distinct sentinels get distinct UUIDs.
+
+**Clause shape: opts always second, args after.** Every clause is `[op, {options}, ...args]`. Field refs are `["field", {options}, fieldId]` (id third), not the legacy MBQL 4 shape `["field", id, opts]`. The same rule holds for aggregations, filters, order-by — the options object never moves out of slot 1.
+
+## MBQL 5 aggregations: name your output columns
+
+Default MBQL 5 aggregations materialize as `count`, `count_where`, `count_where_2`, `avg`, `avg_2`, `sum`, … — ugly when the result is a transform target. Pass `name` and `display-name` in the aggregation's options object to control them. Mint 4 UUIDs (`mb uuid --count 4 --json`) for the slots below before assembling:
+
+```json
+["count",
+ {"lib/uuid": "<UUID:agg-shipped>", "name": "shipments_shipped", "display-name": "Shipments shipped"}]
+
+["count-where",
+ {"lib/uuid": "<UUID:agg-delivered>", "name": "shipments_delivered", "display-name": "Shipments delivered"},
+ ["=", {"lib/uuid": "<UUID:eq-filter>"},
+  ["field", {"base-type": "type/Text", "lib/uuid": "<UUID:status-field>"}, 1779],
+  "delivered"]]
+```
+
+The `name` value becomes the warehouse column name on the materialized table. The `display-name` is the column header in the UI.
+
+## MBQL 5 order-by referencing an aggregation
+
+Order by an aggregation column with an `["aggregation", {…}, "<aggregation-uuid>"]` ref — the third arg is the **string UUID** of the target aggregation's `lib/uuid`, **not** its numeric position. The aggregation's own `lib/uuid` and the ref's third element must be the same minted UUID (string equality); the order-by clause itself and the ref clause each carry their own separate `lib/uuid` in their options. Mint 3 UUIDs and substitute — note that `<UUID:agg-count>` appears twice and gets the same minted value:
+
+```json
+"aggregation": [
+  ["count", {"lib/uuid": "<UUID:agg-count>"}]
+],
+"order-by": [
+  ["desc", {"lib/uuid": "<UUID:order-desc>"},
+    ["aggregation", {"lib/uuid": "<UUID:agg-ref>"},
+     "<UUID:agg-count>"]]
+]
+```
+
+A numeric index (`["aggregation", {…}, 0]`) fails pre-flight with `must be the target aggregation's lib/uuid (string), not a numeric position` at `/stages/0/order-by/0/2/2`.
+
+## Create + run (native SQL)
+
+```bash
+cat > /tmp/transform.json <<'EOF'
+{
+  "name": "user_counts_by_signup_year",
+  "description": "Sample transform: counts users by year of signup",
+  "source": {
+    "type": "query",
+    "query": {
+      "type": "native",
+      "database": <db-id>,
+      "native": {
+        "query": "SELECT date_trunc('year', created_at)::date AS signup_year, COUNT(*)::int AS user_count FROM public.users GROUP BY 1 ORDER BY 1"
+      }
+    }
+  },
+  "target": {
+    "type": "table",
+    "database": <db-id>,
+    "schema": "public",
+    "name": "user_counts_by_signup_year"
+  }
+}
+EOF
+
+TRANSFORM_ID=$(mb transform create --file /tmp/transform.json --profile <name> --json | jq -r '.id')
+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.
+- `--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.
+- 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.
+
+## Inspect
+
+```bash
+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.
+
+## Inspect runs and cancel an in-flight run
+
+```bash
+# Recent runs across all transforms (drains all pages by default; cap with --limit):
+mb transform runs --profile <name> --json
+mb transform runs --transform-id <id> --limit 10 --profile <name> --json
+
+# Fetch one run by RUN id (NOT transform id — the run id comes from `transform run` or `transform runs`):
+mb transform get-run <run-id> --profile <name> --json
+
+# Cancel the currently-running run for a transform:
+mb transform cancel <id> --profile <name> --json
+```
+
+Notes:
+
+- `transform runs` and `transform get-run` parse against the same `TransformRun` schema, so `get-run` returns the same per-run shape as one entry of `runs`. The compact projection is `{id, transform_id, status, run_method, start_time, end_time, message}`. Pass `--full` on `get-run` for the hydrated row including `is_active`, `user_id`, `transform_name`, `transform_entity_id`, `checkpoint_*` fields, and a nested `transform: {id, name, …}` block.
+- `transform cancel` takes the **transform** id and 404s with `Endpoint not found — is this a Metabase instance?` if there is no active run. The response shape is `{canceled: true, id: <transform-id>}`.
+- For native-SQL transforms, cancel marks the run as `canceling` but does **not** kill the warehouse query mid-flight — the query runs to completion, then the run lands as `canceled` (or stays `succeeded` if the cancel arrived after the writer committed). For Python transforms the worker is interrupted directly. Don't expect cancel to free warehouse resources instantly on long native queries; expect it to flip state and prevent downstream consumers from treating the result as good.
+- The `--transform-id` filter on `runs` accepts a single integer; the CLI translates to the server's `transform-ids` query vector. To cross-filter multiple transforms, run `transform runs --json` and `jq` post-hoc.
+
+## Update body: send only writable keys, never round-trip the GET body
+
+`transform update <id>` is **PATCH semantics** — only send the fields you actually want to change. The endpoint accepts exactly these writable keys:
+
+```
+name, description, source, target, run_trigger,
+tag_ids, collection_id, owner_user_id, owner_email
+```
+
+**Don't paste the output of `transform get` into a `transform update` body.** The GET response carries server-side fields (`id`, `entity_id`, `created_at`, `updated_at`, `creator_id`, `last_run`, `target_db_id`, `target_table_id`, `source_type`, `source_database_id`, `source_readable`, `creator`, `owner`, `table`, …) that the PUT endpoint isn't built to handle. Currently, unknown top-level keys flow into `t2/update!` and produce a leaked H2 SQL error like:
+
+```
+Column "TAGS" not found; SQL statement:
+UPDATE "TRANSFORM" SET "TAGS" = (), "UPDATED_AT" = NOW() WHERE "ID" = ? [42122-214]
+```
+
+Two 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.
+
+Right shape — patch only what changes:
+
+```bash
+# Rename only:
+mb transform update <id> --body '{"name":"renamed"}' --profile <name> --json
+
+# Rewrite the SQL only:
+cat > /tmp/patch.json <<'EOF'
+{ "source": { "type": "query", "query": { "type": "native",
+    "database": <db-id>,
+    "native": { "query": "SELECT … FROM public.orders" } } } }
+EOF
+mb transform update <id> --file /tmp/patch.json --profile <name> --json
+
+# Change tag membership (note: tag_ids, not tags):
+mb transform update <id> --body '{"tag_ids":[1,3]}' --profile <name> --json
+```
+
+If you really must round-trip, project to the writable subset:
+
+```bash
+mb transform get <id> --full --profile <name> --json \
+  | jq '{name, description, source, target, run_trigger, tag_ids, collection_id, owner_user_id, owner_email}
+        | with_entries(select(.value != null))' \
+  > /tmp/patch.json
+```
+
+## Iterating on a failing transform
+
+When `transform run` fails and you want to retry with a fixed body, **prefer `transform update <id> --file body.json` over `transform delete <id>` + `transform create`.** Update keeps the same row, the same `entity_id`, the same materialized table, and the same on-disk YAML filename. Concretely this means:
+
+- `git-sync export` produces **one** clean commit containing only the fix, instead of "broken transform" + "remove broken transform" landing as two commits in `git log`.
+- You don't have to chase `_2` suffixes minted when two YAMLs share a `name` on disk (see the `transform create` notes above).
+- The materialized output table either updates in place or, if the SELECT shape changed incompatibly, errors loudly on the next run rather than landing in a parallel `..._2` table the agent has to clean up. (`transform delete-table <id>` resets the column shape if you need a clean slate.)
+
+Recipe:
+
+```bash
+# 1. Try once
+ID=$(mb transform create --file /tmp/t.json --profile <n> --json | jq -r '.id')
+mb transform run "$ID" --wait --profile <n> --json     # → failed
+
+# 2. Fix the body in place; PATCH only what changed.
+#    Source-only patch — keeps name, target, tags untouched on the server.
+cat > /tmp/source-patch.json <<'EOF'
+{ "source": { "type": "query", "query": { "type": "native",
+    "database": <db-id>,
+    "native": { "query": "<fixed SQL here>" } } } }
+EOF
+mb transform update "$ID" --file /tmp/source-patch.json --profile <n> --json
+
+# 3. Re-run
+mb transform run "$ID" --wait --profile <n> --json     # → succeeded
+```
+
+If you really must `create + delete` instead, do the `delete` **before** the first `git-sync export` so the failed entity never lands in git history. Order matters: agents reflex to "export to checkpoint progress," but for transforms an export of a soft-failed state is mostly noise that needs a follow-up cleanup commit. See the `git-sync` skill, "Read state before mutating" for the ordering rule.
+
+## Drop the materialized table (keep the transform)
+
+```bash
+mb transform delete-table <id> --yes --profile <name>
+```
+
+Useful when you've changed the SELECT and want a fresh `CREATE TABLE` on the next run. **`--yes` is required** in non-interactive contexts; without it the command exits with `--yes required to delete non-interactively`.
+
+## Delete the transform
+
+```bash
+mb transform delete <id> --yes --profile <name>
+```
+
+Removes the definition. Whether the materialized table is dropped depends on the server — check with `mb table list --db-id <db-id> --profile <name> --json` if it matters. Same `--yes` rule as `delete-table`.
+
+## Transform jobs (schedules)
+
+A schedule lives in a separate resource (`transform-job`) and references one or more transform ids. Create with the same body-input pattern (`--file body.json`); see `mb transform-job --help` for the verb list. Most ad-hoc agent work is one-off `transform run`, not job authoring.
+
+## Don't (transform-specific)
+
+- 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.