@metabase/cli 0.1.10 → 0.1.12

package/skill-data/semantic-layer/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: semantic-layer
+description: Turn clean, analysis-ready tables into a shared vocabulary the org reuses - Metabase segments (saved filters, e.g. active customers), measures (saved calculations, e.g. net revenue), and metrics (official numbers, e.g. monthly recurring revenue) - so people stop reinventing the same definition five ways. Find the questions people keep asking, propose definitions in plain language, graft them onto what the org already tracks, build them via `mb segment` / `mb measure` / `mb card` create. For a non-technical user who knows their domain. Load when someone wants to "make this reusable", "define X officially", "standardize how we calculate Y", or "create a segment / measure / metric". Strategy skill for designing reusable definitions; for raw `mb segment` / `mb measure` mechanics, use `core`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Semantic Layer
+
+> **Shared contract (read first).** This skill is part of the `robot-data-engineer` family and follows its shared rules: audience is a non-technical user, so no database jargon (skip "normalize"/"grain"; ERD/foreign key are fine; explain "wide"/"long" the first time you use them). Ask before showing PII row-by-row (names, emails, phones) — default to aggregates. When asked for something the CLI can't do (alerts, dashboard filters), name the limit instead of erroring into raw SQL. Honor the autonomy mode the user picked. Full text and the autonomy slider live in the router — run `mb skills get robot-data-engineer` and read its **Shared Contract** if you haven't.
+
+Your job: take the clean, analysis-ready tables that already exist and turn the **questions people keep asking** into **shared, reusable definitions** — so "active customer", "net revenue", and "monthly recurring revenue" mean one thing across the whole organization, not five slightly-different things in five people's saved questions.
+
+You build three kinds of reusable thing. These are real Metabase features with real names — **use the Metabase names** (segment, measure, metric) and teach them to the user as you go. They're product vocabulary, not jargon. Pair the name with a plain gloss the first time, then use it freely:
+
+- **Segment** — a saved filter on a table. A reusable row-selector: "Active customers", "orders over $100", "EU shipments". People pick it from the **Filter** block in the query builder instead of re-typing the conditions. (Docs: <https://www.metabase.com/docs/latest/data-studio/segments>.)
+- **Measure** — a saved aggregation on a table. A reusable calculation: "Net Promoter Score", "average order value". People pick it from the **Summarize** block instead of re-writing the formula. Only works on questions built directly on the measure's table. (Docs: <https://www.metabase.com/docs/latest/data-studio/measures>.)
+- **Metric** — a reusable aggregation that lives in a **collection** (a folder), not bolted to a table. "Monthly recurring revenue", "weekly active users". It's the org's official definition of an important number, can be saved into the **Library**, and can carry a default time dimension for charting. (Docs: <https://www.metabase.com/docs/latest/data-modeling/metrics>.)
+
+Introduce each like: _"I'll save this as a **segment** — that's Metabase's word for a reusable filter, so you can pull up active customers with one click anytime."_ After that, just say "segment".
+
+This skill runs **after** the analysis-ready tables exist (build those with transforms — load `mb skills get transform`). Segments and measures only reach one table — no joins, no nesting (see the docs' Limitations sections) — so a semantic layer on raw, normalized tables is nearly useless: a real answer rarely lives in a single raw table. **Wide clean tables first, segments/measures/metrics second.**
+
+You drive everything through the `mb` CLI. Load the CLI skills you'll need:
+
+```bash
+mb skills get core         # auth, profiles, db/table/field inspection, query, search
+mb skills get mbql         # the definition bodies (filters and aggregations) are MBQL 5
+```
+
+Authentication is the user's job. Check `mb auth list --json`; if one profile exists, use it; if several, ask which; if none, ask them to log in. Pass `--profile <name>` to every command.
+
+---
+
+## Who you're talking to
+
+A **non-technical user who knows their domain well.** They know the business — who an "active" customer is, what counts as "revenue" — but not databases. So:
+
+- **Teach the words a curious non-engineer can follow; skip the deep-internals jargon.** Two sets are fine and worth teaching: Metabase product terms (**segment, measure, metric, collection, Library, the Filter / Summarize blocks**) and common data words a domain user can reasonably learn (**table, column, foreign key, schema, join, filter, row**) — gloss them once, then use them. Avoid **deep-internals jargon** that buys nothing for this user: grain, cardinality, normalize/denormalize, surrogate key, MBQL, `table_id`, materialize. Prefer the plain effect when it's clearer ("this number needs data from two tables" reads easier than "this needs a join across two fact tables") — but you don't have to contort around "foreign key" or "schema".
+- **Talk about the question, then name the object.** Lead with what it does for them, then attach the term: _"I'll save 'big orders' as a segment so you can pull them up with one click."_ Not a bare "I'll create a segment on `table_id` 235."
+- **Be a helpful colleague, not an engineer reporting status.** Elide the wiring (ids, query bodies, the CLI). Ask the one question that actually matters.
+
+---
+
+## Autonomy — honor the mode the user set
+
+The user already picked an autonomy mode (the router's Shared Contract asks the slider once, up front — don't re-ask). Apply it to building definitions:
+
+| Mode                    | What you do                                                                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Check on everything** | Confirm every single definition (name + plain description) before building it.                              |
+| **Balanced** (default)  | Build the obvious ones; ask only on the judgment calls (the prudential list below) and anything ambiguous.  |
+| **Just go**             | Build the whole set, surface judgment calls as "here's what I picked and why — say the word to change any." |
+
+**Two things never bend, in any mode:**
+
+1. **When you're genuinely unsure — ask. Never assume.** "Just go" means _decide the obvious_, not _guess on the unclear_. A wrong-but-confident definition of "active customer" is worse than a one-line question.
+2. **The final gate is a hard stop (see Phase 3).** No mode auto-publishes. You always stop, recap in plain language, and hand the user something to eyeball before anything goes live.
+
+---
+
+## Two kinds of decisions
+
+**Hard rules — absolutes, never ask:**
+
+1. **Never invent what a word means — pin it to real data.** "Active customer" is not yours to define. Before you build a segment for it, find out (from the user, or from how the data actually behaves) what _they_ mean: ordered in the last 90 days? Has a live subscription? Logged in this month? Confirm against actual values, then build to that. A definition built on a guessed meaning is a silent lie everyone then trusts.
+2. **Keep the language at the level set in "Who you're talking to."** Metabase terms and common data words (table, column, foreign key, schema, join) are fine and worth teaching; deep-internals jargon (grain, cardinality, surrogate key, `table_id`) is not.
+3. **Don't bury filters inside measures.** A measure should aggregate _what it's given_; let the user combine it with a segment at question time, rather than welding a filter into the measure. Welded-in filters collide and confuse when someone applies their own filter on top — and the metrics doc explicitly recommends against it. (Use conditional forms like `SumIf`/`CountIf` for "sum only the paid ones" — that's part of the measure's formula, not a hidden row filter.)
+4. **Respect where each thing can reach.** Segments and measures work **only** on a question built _directly_ on their own table — not through a join, not on a question-built-on-a-question (the Limitations sections of both docs say so). If the definition needs more than one table's worth of data, you do **not** force a join into it. You go back and make the analysis-ready table wider first (a transform), then define on that. Quietly building a segment/measure that silently won't show up where the user expects is a hard-rule violation.
+5. **Don't strand a metric on a single data source.** A metric is data-source-bound the same way — defined on table X, it appears only on questions built on table X, not on anything derived from it. If you need it to span sources, the answer is again a wider table first (a transform), not a join in the definition.
+6. **Every definition keeps a clear, plain name and a one-line description in the user's words.** The name is what they'll see in a menu six weeks from now with no memory of this conversation. "Active customers (ordered in last 90 days)" beats "active_seg_v2".
+
+**Prudential calls — genuinely contextual, state your lean, let the user decide** (skip the ask in "Just go" mode — pick your lean, flag it):
+
+- **Which kind of thing is it?** Same wish, three possible homes:
+  - "Let me filter to just the active ones" → a **segment** (saved filter).
+  - "Let me add up revenue the same way everywhere, on this table" → a **measure** on the table.
+  - "Revenue is an _official company number_ people pull onto dashboards" → a **metric** in a collection, with a default month-by-month view so it charts cleanly. Lean: make it a metric when it's a headline figure the org reuses across many questions/dashboards; keep it a measure when it's a table-local convenience.
+- **Where the metric lives.** Metrics sit in a collection (folder). Lean: put the org's blessed ones in the shared **Library** so they surface prominently; keep experimental ones in a working collection until trusted.
+- **Default time dimension for a metric.** A monthly default makes it chart nicely on a dashboard, but doesn't lock anyone out of other groupings. Lean: set a sensible default (usually month) for anything headline; leave it off for raw counts that aren't inherently time-series.
+- **How strict a segment is.** "Active" = last 30 vs 90 days is a real business call with no right answer from the data alone. Lean: surface the few reasonable thresholds with how many rows each catches, let the user pick.
+
+Phrase a prudential call as a lean plus a nod:
+
+> "I'd save 'revenue' as a metric — Metabase's term for an official, reusable number — rather than a table-only measure, since people pull it onto dashboards a lot. Good?"
+
+---
+
+## The process
+
+### Phase 0 — Understand what's reusable (quietly)
+
+Don't narrate. One "Let me see what's here and how people are already slicing it" is plenty. Keep it cheap — compact column listings, `LIMIT`/`GROUP BY` samples, never whole-warehouse rollups.
+
+1. **Confirm the analysis-ready tables exist.** List tables; find the wide, clean ones (a transform step's output). If the user is pointing you at raw normalized tables, say so plainly and suggest building the clean table first — don't build a hobbled semantic layer on raw data.
+2. **Find the questions people keep asking.** Search existing saved questions and dashboards (`mb search`, `mb card list`) for repeated filters and repeated calculations — the same "status = active" written eleven times, five hand-rolled versions of revenue. Those repeats _are_ the semantic layer waiting to be named. This is the highest-signal input; mine it before proposing anything.
+3. **Learn the real meanings.** For every candidate segment ("active", "churned", "high-value"), find what the words map to in actual values — distinct values of a status column, the spread of an amount column. Never define on a guessed meaning (hard rule 1).
+4. **Graft onto what the org already tracks.** This is the part a model does worst and a human does best, so lean on the user: a new definition is far more useful when it lines up with the entities and language the organization _already_ uses. Before inventing "customer health score", ask whether there's already a notion of an active/at-risk customer in their world, and match it. Isolated definitions that don't connect to the existing model are low-value. Ask; don't infer the connection from column names.
+5. **Check reach before promising.** For each candidate, confirm it can actually live where it needs to: a single-table segment/measure must sit on the table people will build questions on; a multi-table answer needs a wider table first (hard rules 4–5). Catch this now, not after building something that won't appear.
+
+### Phase 1 — Propose the shared vocabulary (plain language)
+
+Show, in plain terms, the definitions worth saving — lead with what each _does for the user_, and name the Metabase feature so they learn it:
+
+**Segments — saved filters** (so people pull up the same set with one click):
+
+> • **Active customers** — ordered in the last 90 days. ~2,400 of your 6,000 customers.
+> • **Big orders** — over $100. About 1 in 5 orders.
+
+**Measures — saved calculations** (so everyone adds it up the same way):
+
+> • **Net revenue** — total paid, minus refunds.
+> • **Average order value** — net revenue per order.
+
+**Metrics — official numbers** (the headline figures, for dashboards):
+
+> • **Monthly recurring revenue** — I'd save this as a metric with a month-by-month default, since it's a dashboard headline. Good?
+
+Then surface what you're _not_ saving and why ("I left 'orders this week' alone — it's a one-off, not something you'd reuse"). Ask your prudential questions — one at a time, lean-plus-nod. In "Check on everything" mode, confirm each definition here before Phase 3. In "Balanced", ask only the judgment calls. In "Just go", state your picks and move on.
+
+### Phase 2 — Iterate (cheap, nothing built yet)
+
+Adjust names, meanings, thresholds, and which-kind-of-thing until the user is happy. Re-confirm the final list in one short recap. If a definition turns out to need more than one table, say so plainly and point back to making the table wider — don't smuggle in a join.
+
+### Phase 3 — Build, verify quietly, then hard-stop
+
+Build each agreed definition. Mechanics (load `mbql` for the definition bodies):
+
+- **Segment** → `mb segment create`. Body: `name`, `table_id`, and a `definition` (a flat MBQL filter clause). Update later with `mb segment update <id>` — needs a `revision_message` (the audit note: _why_ it changed). Never delete-and-recreate.
+- **Measure** → `mb measure create`. Body: `name`, `table_id`, and a `definition` holding **exactly one** aggregation. Same `revision_message` rule on update.
+- **Metric** → `mb card create` with the metric shape (`type: "metric"`) — it lives in a **collection**, carries a `dataset_query` (the aggregation) and an optional default time dimension. Put org-blessed ones in the Library collection.
+
+Then **verify what the user can't see**, before you hand back:
+
+- Each segment actually narrows the rows you expect (`mb query` / preview the count — does "active customers" really return ~2,400?).
+- Each measure and metric returns a sane number, not null or an error.
+- Each definition shows up **where the user will look for it** — on a question built on the right table. A segment that silently won't appear (built on the wrong table, or one that would need a join) is the classic silent failure; catch it here.
+
+Then **stop. Hard gate — every mode, no exceptions.** Recap in plain language and hand the user something to open and eyeball:
+
+> Done. Here's the shared set you can now reuse:
+>
+> **Segments** (saved filters — in the **Filter** block on the Customers and Orders tables):
+> • **Active customers** — ordered in the last 90 days
+> • **Big orders** — over $100
+>
+> **Measures** (saved calculations — in the **Summarize** block):
+> • **Net revenue** • **Average order value**
+>
+> **Metric** (in your **Library**, charts by month):
+> • **Monthly recurring revenue**
+>
+> Open any of those tables' Filter or Summarize block in Metabase to see them in place and try one — give it a look before you start building dashboards on top.
+
+End on that plain-language map. It's what the user reads to trust the result — and it's what stops a wrong definition from quietly propagating into everything built next.
+
+---
+
+## A worked example (for your reference, not the user's)
+
+User: _"Everyone calculates 'active users' differently — can you make it official?"_
+
+- **Don't** create a segment from the phrase alone. **Find the real meaning first:** search existing questions — three people filter on "last seen in the last 30 days", two on "subscription status = active". That's the ambiguity to resolve. Ask: "I see two takes on 'active' — seen in the last 30 days, or has a live subscription. Which do you mean?" (hard rule 1).
+- They say "live subscription, and seen in the last 30 days." **Check reach:** both pieces of info must live on the one table people build questions on. If subscription status and last-seen sit on two different tables, a single segment can't span them (hard rule 4) — to the user: "those two facts live in different places right now, so I'll widen your Customers table to carry both first, then save the filter on it." Build the transform, then the segment on the wide table.
+- Build it as a segment on the wide table. **Verify** the row count is plausible. **Recap** plainly and stop: "Saved **Active users** — live subscription and seen in the last 30 days — as a segment on your Customers table; it's in the Filter block there. Have a look before you build on it."
+
+The shape recurs: a word people use loosely → pin it to real values → check it can live where they'll use it → build → verify → hard-stop with a plain recap.

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`).
+Flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`). Deciding _which_ transforms to build — modeling a whole raw database into a set of clean, analysis-ready tables — is the `data-transformation` skill (`mb skills get data-transformation`).
 
 ## Body shape
 
@@ -17,37 +17,32 @@ 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 (see "Create + run" below). MBQL is what the Metabase UI emits and is more verbose; pull a sample with `mb transform get <id> --full --json` if you need its shape.
+Native SQL is the simplest source and the easiest to author by hand. MBQL is what the Metabase UI emits and is more verbose; pull a sample with `mb transform get <id> --full --json` if you need its shape.
 
 For an **MBQL 5** `source.query` (`lib/type: "mbql/query"`), the body shape, the "options object is always second" clause rule, UUID minting, aggregation/order-by refs, naming aggregation output columns, and the `--print-schema` → `--dry-run` validation loop are all in the `mbql` skill — **`mb skills get mbql`**. The MBQL-5 pre-flight on `transform create`/`update` is documented there too (legacy MBQL 4 and native sources skip it). For a transform target, naming your aggregation output columns matters more than usual — a bare `count` / `avg_2` becomes the warehouse column name; see the `mbql` skill's "Naming aggregation output columns".
 
 ## 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')
+# Author the SQL formatted — it's what `mb transform get` and the Metabase editor show.
+cat > ./.scratch/user_counts_by_signup_year.sql <<'SQL'
+SELECT
+  date_trunc('year', created_at)::date AS signup_year,
+  COUNT(*)::int                        AS user_count
+FROM public.users
+GROUP BY 1
+ORDER BY 1
+SQL
+
+# Embed it with jq --rawfile so the newlines survive as \n in valid JSON (don't hand-write the SQL as one line).
+jq -n --rawfile q ./.scratch/user_counts_by_signup_year.sql \
+  '{ 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: $q } } },
+     target: { type: "table", database: <db-id>, schema: "public", name: "user_counts_by_signup_year" } }' \
+  > ./.scratch/transform.json
+
+TRANSFORM_ID=$(mb transform create --file ./.scratch/transform.json --profile <name> --json | jq -r '.id')
 mb transform run "$TRANSFORM_ID" --wait --profile <name> --json
 ```
 
@@ -57,8 +52,8 @@ Notes:
 - 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.
 - `--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.
+- 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 `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.
+- **Keep the SQL formatted.** Author it multi-line in `./.scratch/<name>.sql` and embed with `jq --rawfile` (jq ≥1.6, which JSON-encodes the file so newlines become `\n`). The stored `native.query` is what `mb transform get` and the Metabase editor render — a single-line blob is valid JSON but unreadable when anyone opens the transform. Single-quote the heredoc delimiter (`<<'SQL'`) so the shell leaves `$vars` in the query alone (e.g. Postgres `$1`, `$$`).
 - `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._
@@ -70,14 +65,14 @@ mb transform list --profile <name> --json
 mb transform get <id> --profile <name> --full --json     # full transform incl. last run summary
 ```
 
-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`:
+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.
+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.
 
@@ -104,14 +99,14 @@ Notes:
 
 ## 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:
+`transform update <id>` is **PATCH semantics** — only send the fields you 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:
+**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. Unknown top-level keys flow into `t2/update!` and produce a leaked H2 SQL error like:
 
 ```
 Column "TAGS" not found; SQL statement:
@@ -130,13 +125,15 @@ Right shape — patch only what changes:
 # 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
+# Rewrite the SQL only — author it formatted, embed with jq:
+cat > ./.scratch/orders.sql <<'SQL'
+SELECT …
+FROM public.orders
+SQL
+jq -n --rawfile q ./.scratch/orders.sql \
+  '{ source: { type: "query", query: { type: "native", database: <db-id>, native: { query: $q } } } }' \
+  > ./.scratch/patch.json
+mb transform update <id> --file ./.scratch/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
@@ -148,12 +145,12 @@ If you really must round-trip, project to the writable subset:
 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
+  > ./.scratch/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:
+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:
 
 - `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).
@@ -163,17 +160,18 @@ Recipe:
 
 ```bash
 # 1. Try once
-ID=$(mb transform create --file /tmp/t.json --profile <n> --json | jq -r '.id')
+ID=$(mb transform create --file ./.scratch/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
+cat > ./.scratch/source.sql <<'SQL'
+<fixed SQL, formatted>
+SQL
+jq -n --rawfile q ./.scratch/source.sql \
+  '{ source: { type: "query", query: { type: "native", database: <db-id>, native: { query: $q } } } }' \
+  > ./.scratch/source-patch.json
+mb transform update "$ID" --file ./.scratch/source-patch.json --profile <n> --json
 
 # 3. Re-run
 mb transform run "$ID" --wait --profile <n> --json     # → succeeded

package/skill-data/visualization/SKILL.md

@@ -6,6 +6,8 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 # Visualization: pick the chart, then set it
 
+> **Shared contract (read first).** This skill is part of the `robot-data-engineer` family and follows its shared rules: audience is a non-technical user, so no database jargon (skip "normalize"/"grain"; ERD/foreign key are fine; explain "wide"/"long" the first time you use them). Ask before showing PII row-by-row (names, emails, phones) — default to aggregates. When asked for something the CLI can't do (alerts, dashboard filters), name the limit instead of erroring into raw SQL. Honor the autonomy mode the user picked. Full text and the autonomy slider live in the router — run `mb skills get robot-data-engineer` and read its **Shared Contract** if you haven't.
+
 A card has two presentation fields alongside its `dataset_query`:
 
 - **`display`** — the chart type (`bar`, `line`, `pie`, `scalar`, `map`, `table`, …). One closed set; pick from the enum below.
@@ -13,7 +15,7 @@ A card has two presentation fields alongside its `dataset_query`:
 
 Nothing validates `visualization_settings` — there is no pre-flight to fail past. A `display` typo or a misnamed key is accepted by the API; the card just renders as a default table or drops the setting. So **the feedback loop is read-back, not pre-flight**: after `card create`/`update`, confirm with `mb card get <id> --full --json` (or open the card) that it rendered as intended.
 
-General flag conventions and body-input precedence live in the `core` skill (`mb skills get core`); the `dataset_query` itself is the `mbql` skill's job (`mb skills get mbql`). This skill is only about how the result is displayed.
+Flag conventions and body-input precedence live in the `core` skill (`mb skills get core`); the `dataset_query` itself is the `mbql` skill's job (`mb skills get mbql`). This skill is only about how the result is displayed.
 
 Two steps: **(1) pick the `display` that fits the data**, then **(2) bind the data columns and set options**.
 
@@ -64,7 +66,7 @@ Closed `display` enum (card-level, non-hidden): `table`, `bar`, `line`, `area`,
 
 `graph.dimensions`, `graph.metrics`, `pie.dimension`, `pie.metric`, `scalar.field`, `funnel.metric`, `map.latitude_column`, `sankey.source`, … all take **output column-name strings** — the names the query _produces_, not field ids. A `count` aggregation outputs the column `count`; a breakout on a field outputs that field's name; a named aggregation outputs its `name`. These strings are **identical in the API form and the portable (git-sync) form** — no numeric-vs-name footgun here.
 
-So the names you put in `visualization_settings` come from the query's output, not from `mb field`/`mb table`. If you set `name` on an aggregation (see the `mbql` skill), use that same string here.
+The names come from the query's output, not from `mb field`/`mb table`. If you set `name` on an aggregation (see the `mbql` skill), use that same string here.
 
 ## Minimum-viable settings per chart family (API form)
 
@@ -136,7 +138,7 @@ For anything beyond a single dimension + metric — combo charts, conditional fo
 mb card get <id> --full --json | jq '.visualization_settings'
 ```
 
-Paste that block into your `card create`/`update` body. The server produced it, so it's valid for that `display`. This beats guessing keys from memory, and it's token-cheap.
+Paste that block into your `card create`/`update` body. The server produced it, so it's valid for that `display`.
 
 ## Full per-visualization key catalog
 

package/skills/metabase-cli/SKILL.md

@@ -19,3 +19,9 @@ Before running any `mb` command, load the workflow content from the CLI:
 mb skills get core    # auth, flag conventions, every command group
 mb skills list        # everything available on the installed version
 ```
+
+**Doing a whole job, not one command?** If the user wants an outcome — "make sense of my data", "build a data model", "go from raw data to a dashboard", "answer questions about my data", "be my data analyst", "set up analytics for X" — load the front-door router instead and let it drive:
+
+```bash
+mb skills get robot-data-engineer
+```

package/dist/add-collection-D9wXgmRj.mjs

@@ -1,10 +0,0 @@
-import "./command-augment-BH9qgQ5u.mjs";
-import "./error-BWXBhqLW.mjs";
-import "./runtime-colqvhLf.mjs";
-import "./capabilities-7L9GVMd_.mjs";
-import "./parse-id--iVTCKSo.mjs";
-import "./poll-BucRFJT-.mjs";
-import "./poll-task-DTzKB3T3.mjs";
-import { SyncSettingsUpdateResult, add_collection_default, setCollectionRemoteSynced, syncSettingsUpdateView } from "./add-collection-DUqTrC5T.mjs";
-
-export { add_collection_default as default };

package/dist/auth-cFC5m69m.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-BzrAGJfu.mjs").then((m) => m.default),
-		status: () => import("./status-CvAATvV0.mjs").then((m) => m.default),
-		list: () => import("./list-BGerkRHH.mjs").then((m) => m.default),
-		logout: () => import("./logout-CKBiltoS.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { auth_default as default };

package/dist/card-ClvGX6dQ.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-CGdOC9zX.mjs").then((mod) => mod.default),
-		get: () => import("./get-BYw3xS0X.mjs").then((mod) => mod.default),
-		query: () => import("./query-BVZkK6Qk.mjs").then((mod) => mod.default),
-		create: () => import("./create-CvYKJOcE.mjs").then((mod) => mod.default),
-		update: () => import("./update-BkMWBzvk.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-44EWiXud.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { card_default as default };

package/dist/collection-DjvowSJC.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-36H-dvJZ.mjs").then((mod) => mod.default),
-		get: () => import("./get-reSMTfQi.mjs").then((mod) => mod.default),
-		items: () => import("./items-hgbRYsYD.mjs").then((mod) => mod.default),
-		tree: () => import("./tree-MOQOBeAP.mjs").then((mod) => mod.default),
-		create: () => import("./create-DS52EhPd.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-BZfpjMir.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { collection_default as default };

package/dist/dashboard-BFeURTOw.mjs

@@ -1,21 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/dashboard/index.ts
-var dashboard_default = defineCommand({
-	meta: {
-		name: "dashboard",
-		description: "Manage Metabase dashboards"
-	},
-	subCommands: {
-		list: () => import("./list-DBlsRSpZ.mjs").then((mod) => mod.default),
-		get: () => import("./get-ByZ4HR2T.mjs").then((mod) => mod.default),
-		cards: () => import("./cards-O-nKkQKP.mjs").then((mod) => mod.default),
-		create: () => import("./create-B4f4Pldw.mjs").then((mod) => mod.default),
-		update: () => import("./update-CitS-QRN.mjs").then((mod) => mod.default),
-		"update-dashcard": () => import("./update-dashcard-D_-ura3Y.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-0krZxAXq.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { dashboard_default as default };

package/dist/db-CSH1kwQr.mjs

@@ -1,22 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/db/index.ts
-var db_default = defineCommand({
-	meta: {
-		name: "db",
-		description: "Inspect and sync Metabase databases",
-		alias: "database"
-	},
-	subCommands: {
-		list: () => import("./list-Cd2nOCAx.mjs").then((m) => m.default),
-		get: () => import("./get-Fn9WkNhS.mjs").then((m) => m.default),
-		metadata: () => import("./metadata-BjOrKtnv.mjs").then((m) => m.default),
-		schemas: () => import("./schemas-CgawwI_k.mjs").then((m) => m.default),
-		"schema-tables": () => import("./schema-tables-BEastV_8.mjs").then((m) => m.default),
-		"sync-schema": () => import("./sync-schema-aOPBc3CY.mjs").then((m) => m.default),
-		"rescan-values": () => import("./rescan-values-hWubCruZ.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { db_default as default };

package/dist/document-KdT_Xj6r.mjs

@@ -1,19 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/document/index.ts
-var document_default = defineCommand({
-	meta: {
-		name: "document",
-		description: "Manage Metabase documents"
-	},
-	subCommands: {
-		list: () => import("./list-B9J3ujwn.mjs").then((mod) => mod.default),
-		get: () => import("./get-BC60bhel.mjs").then((mod) => mod.default),
-		create: () => import("./create-D45uFXlo.mjs").then((mod) => mod.default),
-		update: () => import("./update-57uxZWcR.mjs").then((mod) => mod.default),
-		archive: () => import("./archive-_GMNY8wH.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { document_default as default };

package/dist/field-CTFnZI8G.mjs

@@ -1,18 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/field/index.ts
-var field_default = defineCommand({
-	meta: {
-		name: "field",
-		description: "Manage Metabase fields"
-	},
-	subCommands: {
-		get: () => import("./get-Dl62Fy6Y.mjs").then((m) => m.default),
-		values: () => import("./values-BSS4DRxk.mjs").then((m) => m.default),
-		summary: () => import("./summary-CeOnoOq2.mjs").then((m) => m.default),
-		update: () => import("./update-B6mg3AZD.mjs").then((m) => m.default)
-	}
-});
-
-//#endregion
-export { field_default as default };

package/dist/git-sync-C2vib8rx.mjs

@@ -1,28 +0,0 @@
-import { defineCommand } from "citty";
-
-//#region src/commands/git-sync/index.ts
-var git_sync_default = defineCommand({
-	meta: {
-		name: "git-sync",
-		description: "Sync Metabase content with a git remote"
-	},
-	subCommands: {
-		status: () => import("./status-CvKPrV5X.mjs").then((mod) => mod.default),
-		"is-dirty": () => import("./is-dirty-Bb0Rtj7x.mjs").then((mod) => mod.default),
-		"has-remote-changes": () => import("./has-remote-changes-CPz_-uxd.mjs").then((mod) => mod.default),
-		dirty: () => import("./dirty-1OrXpc7E.mjs").then((mod) => mod.default),
-		"current-task": () => import("./current-task-ClcWPPMc.mjs").then((mod) => mod.default),
-		"cancel-task": () => import("./cancel-task-DyhIkNaL.mjs").then((mod) => mod.default),
-		wait: () => import("./wait-D3iSnjMM.mjs").then((mod) => mod.default),
-		import: () => import("./import-DaWgprK6.mjs").then((mod) => mod.default),
-		export: () => import("./export-B5z8w-xo.mjs").then((mod) => mod.default),
-		stash: () => import("./stash-DPQ0c-Cd.mjs").then((mod) => mod.default),
-		branches: () => import("./branches-Jpv-FNds.mjs").then((mod) => mod.default),
-		"create-branch": () => import("./create-branch-KOWUIE72.mjs").then((mod) => mod.default),
-		"add-collection": () => import("./add-collection-D9wXgmRj.mjs").then((mod) => mod.default),
-		"remove-collection": () => import("./remove-collection-HdeAfLyi.mjs").then((mod) => mod.default)
-	}
-});
-
-//#endregion
-export { git_sync_default as default };

package/dist/is-dirty-Bb0Rtj7x.mjs

@@ -1,9 +0,0 @@
-import "./command-augment-BH9qgQ5u.mjs";
-import "./error-BWXBhqLW.mjs";
-import "./runtime-colqvhLf.mjs";
-import "./capabilities-7L9GVMd_.mjs";
-import "./poll-BucRFJT-.mjs";
-import "./poll-task-DTzKB3T3.mjs";
-import { IsDirtyResult, is_dirty_default } from "./is-dirty-DZlI7lQx.mjs";
-
-export { is_dirty_default as default };