@metabase/cli 0.3.1-alpha.support-worktrees.b634907 → 0.3.1-alpha.transform-tests.c0bc2d1

package/dist/{verify-DnBaRmkI.mjs → verify-deF_hThH.mjs}

@@ -1,6 +1,6 @@
-import { n as createClient } from "./client-DYD8WZYy.mjs";
+import { n as createClient } from "./client-C9HBWl6A.mjs";
 import { f as errorMessage, l as TimeoutError, o as MetabaseError, s as NetworkError } from "./predicates-Bkm2IoeX.mjs";
-import { U as tryParseTag, W as SessionProperties, g as USER_AGENT } from "./runtime-CNAZ_FuR.mjs";
+import { F as tryParseTag, I as SessionProperties, u as USER_AGENT } from "./runtime-CJUDVwBu.mjs";
 import { r as HttpError } from "./network-error-D6CiOEBw.mjs";
 //#region ../client/src/version/probe.ts
 const PROBE_PATH = "/api/session/properties";

package/dist/{wait-mPoOZxrw.mjs → wait-Ct0weHol.mjs}

@@ -1,9 +1,9 @@
-import { H as profileFlag, R as connectionFlags, U as worktreeFlag, V as outputFlags, p as renderSummary } from "./cli.mjs";
-import { r as WORKTREE_SCOPE_DETAIL, s as scopeQuery, t as defineMetabaseCommand } from "./runtime-CNAZ_FuR.mjs";
+import { F as outputFlags, I as profileFlag, M as connectionFlags, c as renderSummary } from "./cli.mjs";
+import { t as defineMetabaseCommand } from "./runtime-CJUDVwBu.mjs";
 import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-75SvT7Zv.mjs";
-import { r as parseWaitSchedule } from "./wait-flags-DzytMEG8.mjs";
-import { l as syncTaskView } from "./git-sync-LQIVMNxO.mjs";
-import { a as throwIfFailedTask, i as taskPollOptions, n as formatSyncTask, r as syncTaskIdleView, t as SyncTaskOrIdle } from "./sync-task-G1K47Nvn.mjs";
+import { r as parseWaitSchedule } from "./wait-flags-Cb-bI0RD.mjs";
+import { c as syncTaskView } from "./git-sync-DxD_ng48.mjs";
+import { a as throwIfFailedTask, i as taskPollOptions, n as formatSyncTask, r as syncTaskIdleView, t as SyncTaskOrIdle } from "./sync-task-BACcrs0i.mjs";
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;
 var wait_default = defineMetabaseCommand({
@@ -15,13 +15,10 @@ var wait_default = defineMetabaseCommand({
 		minVersion: 60,
 		tokenFeature: "remote_sync"
 	},
-	worktree: "scoped",
-	details: WORKTREE_SCOPE_DETAIL,
 	args: {
 		...outputFlags,
 		...profileFlag,
 		...connectionFlags,
-		...worktreeFlag,
 		timeout: {
 			type: "string",
 			description: "Polling timeout in ms",
@@ -35,11 +32,9 @@ var wait_default = defineMetabaseCommand({
 	},
 	outputSchema: WaitResult,
 	examples: ["mb git-sync wait", "mb git-sync wait --timeout 300000 --json"],
-	async run({ args, ctx, getClient, getWorktree }) {
+	async run({ args, ctx, getClient }) {
 		const schedule = parseWaitSchedule(args);
-		const mb = await getClient();
-		const scope = await getWorktree();
-		const final = await mb.gitSync.waitForTask(taskPollOptions(schedule), scopeQuery(scope));
+		const final = await (await getClient()).gitSync.waitForTask(taskPollOptions(schedule));
 		if (final === null) {
 			renderSummary({ status: "idle" }, syncTaskIdleView, "No git-sync task is running.", ctx);
 			return;

package/dist/{wait-flags-DzytMEG8.mjs → wait-flags-Cb-bI0RD.mjs}

@@ -1,5 +1,5 @@
-import { n as interruptSignal } from "./cli.mjs";
-import { t as parseId } from "./parse-id-DDCn3VXx.mjs";
+import { t as interruptSignal } from "./cli.mjs";
+import { t as parseId } from "./parse-id-CdZ0-1TM.mjs";
 import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-75SvT7Zv.mjs";
 //#region src/commands/wait-flags.ts
 const waitScheduleFlags = {

package/dist/{window-DSb1tqSe.mjs → window-BkvrP0gB.mjs}

@@ -1,4 +1,4 @@
-import { y as projectForList } from "./cli.mjs";
+import { m as projectForList } from "./cli.mjs";
 //#region src/output/window.ts
 const MAX_REQUEST_PAGE_SIZE = 200;
 function windowList(items, range, serverTotal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metabase/cli",
-  "version": "0.3.1-alpha.support-worktrees.b634907",
+  "version": "0.3.1-alpha.transform-tests.c0bc2d1",
   "description": "Metabase CLI",
   "license": "AGPL-3.0",
   "repository": {

package/skill-data/core/SKILL.md

@@ -6,17 +6,17 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 # metabase-cli (core)
 
-The official Metabase CLI (`mb`) drives a Metabase instance over its REST API: auth, list/get/create/update/delete on every resource, query and transform execution, content search, git-sync (representations ↔ instance), and entity-id translation.
+`mb` drives a Metabase instance over its REST API: CRUD on every resource, query and transform execution, search, git-sync (representations ↔ instance), and entity-id translation.
 
 Top-level command groups (run `mb <group> --help` to discover verbs):
 
 ```
 auth | db | table | field | upload | content-translation | query | card | dashboard | snippet | segment | measure | collection | library
-document | timeline | timeline-event | transform | transform-job | transform-tag | alert | subscription | setting
-search | git-sync | worktree | setup | eid | uuid | upgrade | skills
+document | timeline | timeline-event | transform | transform-job | transform-tag | transform-test | alert | subscription | setting
+search | git-sync | setup | eid | uuid | upgrade | skills
 ```
 
-The conventions below — auth, flags, output, body input — hold across **every** group. Per-command flags and examples live in each command's `--help`; add `--json` for the machine-readable form with the output JSON Schema. A few flows have their own skills (see "Specialized skills"). When a card needs a query, prefer MBQL over native SQL (portable, pre-flight-validated — load `mbql`); fall back to native SQL when MBQL can't express it.
+The conventions below — auth, flags, output, body input — hold across **every** group. When a card needs a query, prefer MBQL over native SQL (portable, pre-flight-validated — load `mbql`); fall back to native SQL when MBQL can't express it.
 
 ## Auth & profiles
 
@@ -28,7 +28,7 @@ mb auth status --json                    # → {profile, present, url} for the d
 mb auth status --profile <name> --json   # health probe for one profile
 ```
 
-`auth list` is the primary enumeration path — one call returns every profile with sanitized URL, an `authenticated` flag, and a probe `status` (`ok` / `auth-failed` / `network-error` / `server-error` / `not-probed`). Use it before asking which profile to pick.
+`auth list` is the primary enumeration path — one call returns every profile with sanitized URL, an `authenticated` flag, and a probe `status` (`ok` / `auth-failed` / `network-error` / `server-error` / `not-probed`).
 
 - One profile and intent doesn't disambiguate → use it.
 - Several → ask via `AskUserQuestion`, presenting the names from `auth list`.
@@ -47,8 +47,6 @@ Once a name is established, pass `--profile <name>` to **every** subsequent comm
 
 **`--wait` for async operations.** `transform run`, `git-sync import`, and similar verbs return immediately by default. Pass `--wait` whenever the next step depends on completion — without it you race the operation and see "not ready" / transient connection refusals.
 
-**`--worktree <id|branch>` scopes a command to a git-sync worktree** — an isolated checkout of one branch's content in the same instance (admin-only, v64+). Precedence: flag, then `MB_WORKTREE`, then the profile's pin (`mb worktree pin <ref>` / `unpin`). **The pin is a lock, not a default:** flag and env may only re-state it, a different worktree exits 2 — that is how a harness confines an agent to one worktree. Each command's `worktree` policy shows in `--help --json`: `scoped` honors the scope, `any` ignores it and takes no `--worktree`, `main-only` (`transform run`, main-app writes) refuses under one — report that refusal rather than unpinning. Workflow: the `git-sync` skill.
-
 **Some "lookup" verbs return JSON envelopes, not bare values.** `mb setting get <key>` returns `{"key": "...", "value": ...}`. Extract before reusing:
 
 ```bash
@@ -62,7 +60,7 @@ Every list/get verb supports the same output flags:
 - `--json` — emit the full JSON envelope, safe for `jq`. Default is human-readable text.
 - `--full` — include every field (the compact projection is the default, and is the agent-facing contract).
 - `--fields a,b.c.d` — project specific dot-paths. Mutually exclusive with `--full`. **Paths are relative to each `data[]` item on list verbs, and to the root on single-item verbs.** So it's `--fields id,name` on `… list` / `database schema-tables` (`data.id` and `data[].id` both fail with `unknown field path: "data.id"`), and `--fields id,name,display` on `card get`, `--fields data.rows` on `mb query` (whose `data` is an object).
-- `--max-bytes <n>` — cap output size. Default 24576 (sized to fit under agent-harness tool-output limits); `0` disables. On a list it drops trailing items and sets `truncated` (see below). Single-item commands (`get`) never truncate — over the cap they throw a `ConfigError` (exit 2: "output is N bytes, over the M-byte --max-bytes cap; …") whose tail names the remedy: on schema-shaped commands it is the exact narrower command to run instead — follow it rather than raising the cap.
+- `--max-bytes <n>` — cap output size. Default 24576; `0` disables. On a list it drops trailing items and sets `truncated` (see below). Single-item commands (`get`) never truncate — over the cap they throw a `ConfigError` (exit 2: "output is N bytes, over the M-byte --max-bytes cap; …") whose tail names the remedy: on schema-shaped commands it is the exact narrower command to run instead — follow it rather than raising the cap.
 - JSON output is a single line when stdout is piped (pretty-printed only at a TTY) — always parse it, never scrape by line position.
 
 ## List windows and resumption
@@ -74,7 +72,7 @@ Every list verb takes `--limit <n>` (items this call returns) and `--offset <n>`
 - **`truncated` means the byte cap cut the output, not that the data ran out.** `has_more`/`next_offset` are recomputed to the cut point, so a capped list resumes like any window. Its `bytes` is what the untruncated answer would have measured, so it sizes the work left rather than the reply you hold. Narrow rows with `--fields` rather than raising `--max-bytes` — the cap counts only what you asked for, so `--fields` buys rows directly. A capped list always returns at least one row; when not even one fits it exits 2 with "the smallest response this list can produce is N bytes, over the M-byte --max-bytes cap; …".
 - `limit` is echoed only when you passed `--limit` — except `mb search`, which defaults to `--limit 20` (an unbounded search is expensive server-side) and so always reports one. On nouns the server doesn't page, one large `--limit` with narrow `--fields` is a single request; many small `--offset` hops are one request each.
 
-The whole walk, literally:
+The whole walk:
 
 ```bash
 offset=0
@@ -125,27 +123,27 @@ mb transform --help --json | jq -r '.commands[].command'  # verbs under "transfo
 
 ## Resource quirks worth memorizing
 
-Routine verb shapes (list / get / create / update), every flag, and output schemas live in each command's `--help` (add `--json`). Below is only what help does _not_ tell you: footguns and non-obvious behaviors.
+Only what `--help` does _not_ tell you: footguns and non-obvious behaviors.
 
-- **db traversal: the hydration ladder.** Start with `database get <db-id> --include tables` — the compact table map (id, name, schema, description per table), one call that fits most databases. Then `table fields <table-id>` per relevant table (bounded: fields are per-table). `--include tables.fields` is the full rollup — small databases only. Hundreds of tables? Traverse by schema (`database schemas <db-id>` → `database schema-tables <db-id> <schema>`) or look tables up by name (`search <term> --models table --db-id <db-id> --limit 10`). `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
-- **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact; `--full` also carries FK targets and dimensions) or use `table fields <id>` (list envelope). `table update` patches table-level metadata only; physical columns aren't editable.
+- **db traversal: the hydration ladder.** Start with `database get <db-id> --include tables` — the compact table map (id, name, schema, description per table), one call that fits most databases. Pick the relevant tables, then `table fields <table-id>` per table (bounded: fields are per-table). `--include tables.fields` is the full rollup — small databases only. Hundreds of tables? Traverse by schema (`database schemas <db-id>` → `database schema-tables <db-id> <schema>`) or look tables up by name (`search <term> --models table --db-id <db-id> --limit 10`). `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
+- **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact; the underlying query_metadata response also carries FK targets and dimensions, visible under `--full`) or use `table fields <id>` (list envelope). `table update` patches table-level metadata only; physical columns aren't editable.
 - **field has no `list`.** Fields are per-table — get them via `table get <id> --include fields`. Never enumerate fields across a whole db (context blow-up). `field summary` is live cardinality `{field_id, count, distincts}`; `field values` is the cached distinct set (`has_more_values: true` ⇒ truncated cache). `field update` patches metadata only (`base_type` isn't editable) — this is where you set a column's `semantic_type` or foreign-key target.
 - **upload (CSV → tables).** `upload csv --file <path>` creates a new table + model (prints `{model_id, table_id}`); `upload append <table-id>` / `upload replace <table-id> --file <path>` add to / overwrite a table **previously created by upload** (columns must match). The destination db+schema is admin-configured, not per-call — check with `mb setting get uploads-settings --json` (`db_id: null` ⇒ uploads off/unconfigured; needs admin to read). `--collection <id|root>` only sets the model's collection. Max 50 MB. Errors: **"The uploads database is not configured."** = no db has uploads enabled; **"Uploads are not enabled."** = the append/replace target isn't an uploaded table.
-- **content-translation.** EE-only (`content_translation` premium feature), admin-only, separate from Remote Sync. `content-translation download > translations.csv` streams the complete active dictionary; `content-translation upload --file translations.csv` replaces every active translation with the file. Always upload the canonical complete CSV, never a partial patch. An empty dictionary downloads as Metabase's four-row sample — don't re-upload it as real translations. Dictionaries are limited to 1.5 MiB.
+- **content-translation.** EE-only (`content_translation` premium feature), admin-only, and separate from Remote Sync. `content-translation download > translations.csv` streams the complete active dictionary; `content-translation upload --file translations.csv` replaces every active translation with the file's contents. Always upload the canonical complete CSV, never a partial patch. An empty dictionary downloads as Metabase's four-row sample dictionary — don't re-upload it as real translations. Metabase limits dictionaries to 1.5 MiB.
 - **card.** `dataset_query` is the **flat** `mbql/query` value, not a legacy `{type:"query",query:…}` envelope (→ `mbql`). `--export-format csv|xlsx` streams the raw export (pipe to a file), bypassing the JSON envelope. `archive` is the only delete; unarchive with `update --body '{"archived":false}'`. `visualization_settings` keys are scoped by `display` and aren't pre-flighted — see `visualization`.
-- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). Every dashcard must include `card_id`, including existing rows; use `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create` accepts the **same** `dashcards` array in its initial body, so lay out the whole dashboard in one call. `create`/`update` pre-flight every positive `card_id` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a half-width card). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix). Layout patterns and per-chart default sizes → the `dashboard` skill; load it before composing any `dashcards` array.
-- **dashboard parameters (filters).** A dashboard's `parameters` array holds its filter widgets; they're part of the dashboard record, so read them with `dashboard get <id> --fields parameters --json` (no separate verb). **Editing replaces the _whole_ array** (like dashcards), so it's a read-modify-write loop and omitting a parameter deletes it. A parameter only filters a card once it is **mapped** onto that dashcard's `parameter_mappings` — an unmapped parameter is an inert widget. `type` is a **closed enum**; an unlisted value is a hard parse error that echoes the allowed set back. `dashboard parameter-values <id> <parameter-id> [--query <substr>]` fetches a widget's selectable values (`{values, has_more_values}`; `--query` is a case-insensitive substring match). Parameter types, ids, mapping targets, and value sources → the `dashboard` skill; load it before authoring a `parameters` array.
+- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). Every dashcard must include `card_id`, including existing rows; use `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create` accepts the **same** `dashcards` array in its initial body, so lay out the whole dashboard in one call. `create`/`update` pre-flight every positive `card_id` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a card filling only half the width). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix). Layout patterns and per-chart default sizes → the `dashboard` skill.
+- **dashboard parameters (filters).** A dashboard's `parameters` array holds its filter widgets; they're part of the dashboard record, so read them with `dashboard get <id> --fields parameters --json` (no separate verb). **Editing replaces the _whole_ array** (like dashcards), so it's a read-modify-write loop and omitting a parameter deletes it. A parameter only filters a card once it is **mapped** onto that dashcard's `parameter_mappings` — an unmapped parameter is an inert widget. `type` is a **closed enum**; an unlisted value is a hard parse error that echoes the full allowed set back to you. `dashboard parameter-values <id> <parameter-id> [--query <substr>]` fetches a widget's selectable values (`{values, has_more_values}`; `--query` is a case-insensitive substring search). Parameter types, ids, mapping targets, and value sources → the `dashboard` skill; load it before authoring a `parameters` array.
 - **alert / subscription are two unrelated systems.** `alert` watches one **card** and fires on a send condition (`/api/notification`: a cron string, `channel/email`-prefixed handlers, typed recipients); `subscription` delivers one **dashboard** on a schedule (`/api/pulse`: structured `schedule_type` + hour/day/frame, bare `email` channels, `{id}|{email}` recipients). The bodies are not interchangeable. Both silently deliver nowhere if the server has no SMTP / Slack app — check `mb setting get 'email-configured?'` (quote it; the `?` is a shell glob) before creating either. Their list-valued fields (`handlers`/`subscriptions`, `channels`/`cards`) **replace wholesale** on update, so adding one recipient is a read-modify-write. `mb card alerts <id>` and `mb dashboard subscriptions <id>` list what's already attached to a card/dashboard; `archive` deactivates rather than deletes. Load the `notification` skill before authoring either body.
 - **snippet `--archived` is a swap, not a union** — list returns _either_ active _or_ archived rows, never both. (Same for `--filter archived` on dashboard/collection.)
 - **segment / measure.** `update` and `archive` require a non-blank `revision_message` (audit-logged); the CLI does not synthesize it on `update`. `archive` defaults to `"Archived via mb CLI"` — override with `--revision-message`. `definition` is a flat MBQL clause (→ `mbql`): segment = a filter, measure = exactly one aggregation.
-- **timeline / timeline-event.** Timelines are collection-scoped event annotations for time-series charts: a timeline's events render only on time-series questions saved in the **same collection** (`collection_id`; null = root) — sub-collections do **not** inherit, and events never draw on dashboard cards, only in the question (and collection) view. An event draws only when its `timestamp` falls inside the chart's displayed time range. Event `create` requires `timestamp` (ISO 8601), `timezone` (IANA name), `time_matters` (true = the time of day is significant, false = date-only), and `timeline_id` — the API never auto-creates a default timeline (that's UI-only). There is no `timeline-event list`; enumerate with `timeline events <id>` (`--archived` to include archived). Archiving a timeline cascades `archived` to its events; `delete` is a **hard** delete of the timeline and all its events — prefer `archive`.
+- **timeline / timeline-event.** Timelines are collection-scoped event annotations for time-series charts: a timeline's events render only on time-series questions saved in the **same collection** (`collection_id`; null = root) — sub-collections do **not** inherit, and events never draw on dashboard cards, only in the question (and collection) view. To annotate a question's chart, create the timeline in that question's collection, then add events; an event only draws when its `timestamp` falls inside the chart's displayed time range. Event `create` requires `timestamp` (ISO 8601), `timezone` (IANA name), `time_matters` (true = the time of day is significant, false = date-only), and `timeline_id` — the API never auto-creates a default timeline (that's UI-only). There is no `timeline-event list`; enumerate with `timeline events <id>` (`--archived` to include archived). Archiving a timeline cascades `archived` to its events; `delete` is a **hard** delete of the timeline and all its events — prefer `archive`.
 - **collection `<ref>`** accepts four forms only — positive int, `root`, `trash`, or a 21-char entity_id; anything else is a client-side `ConfigError`. `collection items` pages the server endpoint, pulling only as far as the output cap can show — read `has_more`/`next_offset` to continue. `collection tree` is **JSON-only** (`--format text` is rejected). A transform collection needs `collection create --namespace transforms`.
 - **setting set** parses the value as **strict JSON**: a string is `'"value"'` (inner quotes), booleans `true`/`false`, numbers bare. Wrong quoting silently errors — confirm with `setting get <key>` after. `setting get --json` works on every value type (wrapping bare-text responses into `{key, value}`).
 - **search vs. list.** For plain enumeration of cards/dashboards/collections use the dedicated `… list` verbs; reach for `search --models <kind>` only for ranking against a query string or a cross-resource lookup.
-- **transform.** Iterate with `transform update <id>`, never `delete` + `create` (keeps the row, `entity_id`, materialized table, and YAML filename — avoids `_2` suffixes and noisy git history). `transform run` needs `--wait` (or `--sync`, which also waits for the output table to register and returns `target_table_id`) or you get only `{run_id, final:null}`. (→ `transform`.)
+- **transform.** Iterate with `transform update <id>`, never `delete` + `create` (keeps the row, `entity_id`, materialized table, and YAML filename — avoids `_2` suffixes and noisy git history). `transform run` needs `--wait` (or `--sync`, which also waits for the output table to register and returns `target_table_id`) or you get only `{run_id, final:null}`. `transform-test run <id>` checks a transform against fixtures in temp tables — no real table is read — and exits non-zero unless it passes (v65+). (→ `transform`.)
 - **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only — errors against an already-configured one. Mostly for bootstrapping local / e2e instances.
 - **eid** translates a string entity id → numeric id: `mb eid --model <model> <eid1,eid2> --json`. Entity ids are NanoIDs that can start with `-`, which the positional form misreads as a flag (shell quotes don't help) — for those, use `--body '{"entity_ids":{"card":["-…"]}}'` (the id is a JSON string value, immune to flag parsing).
-- **library.** EE-only (`library` premium feature, v59+). The Library is a curated subtree (`library-data` "Data" + `library-metrics` "Metrics" under a `library` root): tables published to **Data** appear first in data pickers and rank up in search; metrics saved to **Metrics** are prioritized in nav, search, and the query builder — it's how you tell people (and agents) which to start from. `library get` shows the Library and its Data/Metrics collection ids; `library create` provisions it (idempotent). `library publish --table-ids/--db-ids/--schemas` publishes tables into Data — it **resolves the Data collection itself and creates the Library if absent**; each `--schemas` entry is `<db-id>:<schema>` (e.g. `1:public`), not a bare name. `publish` cascades to upstream FK dependencies, `unpublish` to downstream dependents; both need **admin or data-analyst** (Curate alone won't publish) and exit **403** without write **and** query permission on every affected table. `table get`/`table list` carry `is_published` (`collection_id` under `--full`). Good candidates are finished, analysis-ready tables — clean up via transforms first. Publishing does not put the Data collection in the git-sync scope: `mb git-sync add-collection <data-collection-id>` is what makes exports carry the published tables' metadata (see the `git-sync` skill).
+- **library.** EE-only (`library` premium feature, v59+). The Library is a curated subtree (`library-data` "Data" + `library-metrics` "Metrics" under a `library` root): tables published to **Data** appear first in data pickers and rank up in search; metrics saved to **Metrics** are prioritized in nav, search, and the query builder. `library get` shows the Library and its Data/Metrics collection ids; `library create` provisions it (idempotent). `library publish --table-ids/--db-ids/--schemas` publishes tables into Data — it **resolves the Data collection itself and creates the Library if absent** (no collection id to find); each `--schemas` entry is `<db-id>:<schema>` (e.g. `1:public`), not a bare name. `publish` cascades to upstream FK dependencies, `unpublish` to downstream dependents; both need **admin or data-analyst** (Curate alone won't publish) and exit **403** without write **and** query permission on every affected table. Publish status shows on the table: `table get`/`table list` carry `is_published` (`collection_id` under `--full`). Publish finished, analysis-ready tables — clean/combine via transforms first. Publishing does not put the Data collection in the git-sync scope: on a remote-sync instance, `mb git-sync add-collection <data-collection-id>` is what makes exports carry the published tables' metadata (see the `git-sync` skill).
 - **query / uuid.** `mb query` is the ad-hoc MBQL surface (`--print-schema` → `--dry-run` → run); `mb uuid --count <n>` mints the `lib/uuid` values MBQL clauses need. Both live in `mbql`.
 
 ## Specialized skills (load on demand)
@@ -159,9 +157,10 @@ This file is enough for any single-command task. For anything deeper, load the r
 - **`metadata`** — setting field/table metadata: semantic types, foreign-key targets, dropdown/scan behavior, and column visibility, and the downstream features each unlocks. Load when editing what a column _means_, not its data.
 - **`notification`** — scheduled delivery: question alerts (`mb alert`) and dashboard subscriptions (`mb subscription`). Choosing between them, the two schedule/recipient contracts, channel prerequisites, testing a send.
 - **`transform`** — transform body JSON, create + run-with-wait, run inspection, tags, jobs.
+- **`transform-test-plan`** — deciding _what_ to test in a transform: the fixture cast, the expectations, the coverage matrix. (`transform` has the `mb transform-test` shapes.)
 - **`document`** — Metabase documents (TipTap body, embedding cards).
-- **`git-sync`** — round-tripping content to/from a git remote, and worktrees.
-- **`data-workflow`** — the guided, end-to-end data workflow: investigate raw data, build clean analysis-ready tables, define reusable segments/measures/metrics, answer questions, build dashboards. **Start here when the user states a goal rather than a single verb** — "make sense of my data", "build a data model", "go from raw data to a dashboard", "set up analytics for X". It detects where the data is and routes to the right stage.
+- **`git-sync`** — round-tripping content to/from a git remote.
+- **`data-workflow`** — the guided, end-to-end data workflow: investigate raw data, build clean analysis-ready tables, define reusable segments/measures/metrics, answer questions, build dashboards. **Start here when the user states a goal rather than a single verb** — "make sense of my data", "build a data model", "go from raw data to a dashboard", "be my data analyst", "set up analytics for X". It detects where the data is and routes to the right stage.
 
 If a task spans more than one, load each. `mb skills list` enumerates everything on the installed version.
 

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

@@ -1,6 +1,6 @@
 ---
 name: git-sync
-description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections, Library-published table/field metadata) 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", "push my changes to the repo", "open a PR with my Metabase changes", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …` / `mb worktree …`. Also covers worktrees — isolated per-branch checkouts of transforms and other content — for "work on this branch in isolation", "create a worktree", "pin the profile to a worktree", "export the worktree and open a PR".
+description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections, Library-published table/field metadata) 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", "push my changes to the repo", "open a PR with my Metabase changes", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -40,7 +40,6 @@ Pulls the configured branch and applies it to the instance. Polls until the task
 | `--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. |
-| `--merge`         | Three-way merge remote changes instead of failing on divergence. Confirm first.      |
 | `--timeout <ms>`  | Polling deadline. Default 600 000.                                                   |
 | `--interval <ms>` | Polling cadence. Default 2 000.                                                      |
 
@@ -63,7 +62,6 @@ Pushes Metabase-side changes back to the configured remote. `-m` is the commit m
 | `--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.    |
-| `--merge`           | Three-way merge instead of failing on divergence.        |
 | `--no-wait`         | Don't poll.                                              |
 
 Workflow:
@@ -98,94 +96,6 @@ mb git-sync stash --profile <n>                           # export current state
 
 `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.
 
-## Worktrees (isolated branch checkouts)
-
-A **worktree** is a self-contained checkout of one branch's content inside the same instance. Transforms, transform tags, snippets, `transforms`-namespace collections, the Library, cards, dashboards, and documents are tagged with the worktree's id; tables and fields stay shared with the main app. It is how a chain of transforms gets built, exported, and reviewed as a PR without touching production content. Admin-only, and needs Metabase v64+ with the `remote_sync` feature.
-
-Two hard limits, up front:
-
-- **A worktree's transforms cannot be run.** `mb transform run` refuses while a worktree scope is in force, and the server rejects the run anyway. There is no workaround to find — run the transform in the main app after the branch is merged and imported, and say so rather than trying to validate the SQL by running it in the worktree.
-- **A worktree is bound to its branch for life.** No branch switching inside one; a different branch means a different worktree.
-
-### Where am I? Check before touching import/export
-
-```bash
-mb auth status --profile <n> --json | jq '.worktree'      # {id, branch} when the profile is pinned, else null
-mb git-sync status --profile <n> --json | jq '.worktree'  # the scope this command ran under
-mb worktree list --profile <n> --json                     # every worktree on the instance
-```
-
-A pinned profile pushes to the worktree's branch; an unpinned one pushes to whatever `remote-sync-branch` points at. Confusing the two is how worktree work lands on the team's tracked branch, so read the pin before the first `export`.
-
-### Preconditions before creating one
-
-1. **The user named the branch.** Create a worktree only for a branch the user asked you to work on.
-2. **A branch holds at most one worktree.** Check `mb worktree list --json` first; a duplicate fails with the server's `A worktree for branch '<b>' already exists.` — reuse it with `mb worktree pin <branch>` instead.
-3. **A pinned profile is already confined.** `mb worktree create` for any other branch is refused, because a second worktree from a pinned session would escape the pin.
-
-### The workflow
-
-```bash
-# 1. Create the worktree and pin the profile to it. Mints the branch on the remote when missing
-#    (--no-checkout, so the main app's tracked branch is untouched), then pulls the branch in.
-mb worktree create feat/order-metrics --pin --profile <n> --json
-
-# 2. Edit transforms. Scoped commands need no extra flag once the profile is pinned.
-mb transform create --file ./.scratch/transform.json --profile <n> --json
-mb transform list --profile <n> --json        # only this worktree's transforms
-mb transform update <id> --file ./.scratch/patch.json --profile <n> --json
-
-# 3. Read state before pushing — same rule as the main app.
-mb git-sync status --profile <n> --json       # branch, dirty flag, current task, all scoped
-mb git-sync dirty  --profile <n> --json       # exactly what will be committed
-
-# 4. Dry-run the push, read the answer, then push.
-mb git-sync export-preflight --profile <n> --json
-mb git-sync export -m "add order metrics transforms" --profile <n>
-
-# 5. Open the PR from the branch with plain git / gh, and let a human review and merge it.
-
-# 6. Retire the worktree once the PR is merged. This clears the pin it was holding.
-mb worktree delete feat/order-metrics --profile <n> --json
-```
-
-`export-preflight` answers `{has_changes, clean, conflicts, summary: {added, updated, removed}, force_push_casualties: {deleted, overwritten}, reason}`. Read it before every worktree export: `clean: true` with empty `conflicts` is a push that applies as-is; a non-empty `conflicts` or `force_push_casualties` is a conversation with the user, not a `--force`.
-
-The main app pulls the merged branch from a **different, unpinned** profile — `git-sync import` into the main app and `transform run` are both main-app operations and a pinned profile refuses them:
-
-```bash
-mb git-sync import --profile <main-app-profile>
-mb transform run <id> --wait --profile <main-app-profile> --json
-```
-
-### Scope precedence and what a pinned profile refuses
-
-The scope comes from `--worktree <id|branch>`, else `MB_WORKTREE`, else the profile's pin. **The pin is a lock, not a default:** while it stands, the flag and the env var may only re-state it, and naming a different worktree exits 2 with `profile "<p>" is pinned to worktree <id> (<branch>); refusing --worktree <x>`.
-
-Under a scope, a command that changes or runs main-app state refuses before any request and exits 2 — `transform run` / `cancel`, `card` / `library` writes, and the main-app git-sync verbs `stash`, `create-branch`, `add-collection`, `remove-collection`:
-
-```
-transform run is not available inside a worktree (scope: worktree 3 (feat/order-metrics) from the profile pin); it changes main-app content. Unpin the profile (`mb worktree unpin`) or drop MB_WORKTREE to run it against the main app.
-```
-
-Two more refusals belong to the scope:
-
-- Fetching a row that lives elsewhere: `transform 12 is not in worktree 3 (feat/order-metrics); refusing to touch main-app content`.
-- `--branch` on `import` / `export` / `export-preflight`: `a worktree is pinned to its branch; drop --branch`.
-
-### Confirmations these flags need
-
-- `--force` (on `import`, `export`, and `worktree delete`) and `--merge` (on `import` / `export`) are **lossy or history-rewriting** — ask the user first, with `AskUserQuestion`, naming what gets discarded. `export-preflight`'s `force_push_casualties` is the list to show them.
-- `mb worktree delete` refuses a worktree holding unpushed changes: `worktree <id> (<branch>) has unpushed changes; push them with mb git-sync export or pass --force to discard`. Export first, or ask before forcing — the content in a worktree exists nowhere else once it is gone.
-
-### Don't (worktrees)
-
-- **Don't unpin to reach the main app.** The pin is the isolation boundary a harness put there; `mb worktree unpin` to get past a refusal turns an isolated session into one that can write production content. Report the refusal and what you would need instead.
-- **Don't run a worktree's transforms**, and don't route around the refusal with `mb query`, a native card, or a second profile. Validate the query shape with `--dry-run` (see `mbql`) and run it for real in the main app after the merge.
-- **Don't create worktrees for branches you were not asked to touch.** A worktree checks a whole branch's content into the instance; an unwanted one is content to clean up, not a free experiment.
-- **Don't `git-sync export` from the main app while the work lives in a worktree.** It pushes the main app's state to the tracked branch and the worktree's edits are not in it. Check `.worktree` in `git-sync status` before exporting.
-- **Don't hand-write the branch's YAML in the repo to "help" the PR.** Worktree content round-trips through `export` exactly like main-app content — see the first entry of the general "Don't" list below.
-
 ## Polling and cancelling
 
 ```bash

package/skill-data/transform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: transform
-description: Author and run Metabase transforms via `mb` — body shape (native SQL or structured MBQL), create + run-with-wait, run inspection, dependencies, cancel, the `update`-vs-recreate iteration rule, the writable-keys-only PATCH contract, plus transform tags and tag-driven transform-job schedules. Load when the user touches transforms — "create a transform", "run a transform", "fix a failing transform", "list transform runs", "cancel a running transform", "manage transform tags", "run a transform job", or anything `mb transform …` / `mb transform-job …` / `mb transform-tag …`.
+description: Author and run Metabase transforms via `mb` — body shape (native SQL or structured MBQL), create + run-with-wait, run inspection, dependencies, cancel, the `update`-vs-recreate iteration rule, the writable-keys-only PATCH contract, transform tests (fixtures and expectations run against temp tables), plus transform tags and tag-driven transform-job schedules. Load when the user touches transforms — "create a transform", "run a transform", "fix a failing transform", "test a transform", "list transform runs", "cancel a running transform", "manage transform tags", "run a transform job", or anything `mb transform …` / `mb transform-job …` / `mb transform-tag …` / `mb transform-test …`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -48,7 +48,7 @@ mb transform run "$TRANSFORM_ID" --wait --profile <name> --json
 - `--wait` polls until status is `succeeded` or `failed`. Without it you get only `{message: "Transform run started", run_id, final: null}` and must poll yourself — don't put bare `transform run` in a tight loop; let `--wait` do the polling.
 - `--sync` implies `--wait`, then waits until the run registers its output table (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 `null` when `--wait` is omitted or the run never started, otherwise a full `TransformRun` with `status` and `message`. On a failed run (`final.status` ∈ {`failed`, `timeout`, `canceled`}) the CLI exits 1 and writes a one-line `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.
-- `transform create --json` returns the agent-facing compact projection: `{id, name, description, source_type, target: {type, database, schema, name}, target_db_id, worktree_id}`. Read `target.schema`/`target.name` directly off it — no follow-up `transform get`.
+- `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 it — no follow-up `transform get`.
 - 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", prefer `transform update <id>` — see "Iterating on a failing transform".
 - **`collection_id` only accepts a collection in the `:transforms` namespace.** Transforms aren't filed next to cards and dashboards — a normal analytics collection id 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 provision one with `mb collection create --body '{"name":"…"}' --namespace transforms --json` (see `core`) and pass the returned `id`. Cards and dashboards you build **on top of** the output table go in ordinary collections — so "put the transform and its dashboard in collection X" means _X holds the dashboard + cards; the transform stays in the transforms namespace._
 
@@ -71,14 +71,6 @@ On `target_table_id: null` (still syncing when the poll timed out; exit 0) re-po
 
 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.
 
-## Editing transforms safely in a worktree
-
-A **worktree** is an isolated checkout of one git branch's content inside the same instance — the way to build a chain of transforms for PR review without touching production transforms or their tables. The lifecycle (create → pin → export-preflight → export → PR → delete) lives in the `git-sync` skill, section "Worktrees": **`mb skills get git-sync`**. What matters while authoring:
-
-- **`worktree_id` says where a transform lives.** `transform get` and `transform list` carry it: an integer for a worktree's transform, `null` for a main-app one. Read it before editing anything you did not create in this session — under a scope, `update` / `delete` / `delete-table` of a main-app transform is refused with `transform <id> is not in worktree <n> (<branch>); refusing to touch main-app content`.
-- **The scope is implicit once the profile is pinned.** With `--worktree <id|branch>`, `MB_WORKTREE`, or a pin in force, `transform list` shows only that worktree's transforms and `transform create` files what it creates into it. Without a scope both address the main app, whose listing excludes every worktree's rows.
-- **`transform run` is refused under a scope**, and the server rejects worktree runs anyway: `transform run is not available inside a worktree (…); it changes main-app content.` The create → run → fix loop therefore does not close inside a worktree. Validate the query with `--dry-run` (see `mbql`) before creating, iterate the body with `transform update`, and run it in the main app once the branch is merged and imported. Don't unpin, don't switch to another profile, and don't stand in a run with `mb query` — tell the user the run waits for the merge.
-
 ## Inspect runs and cancel an in-flight run
 
 ```bash
@@ -180,6 +172,64 @@ 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 — an export of a soft-failed state is noise that needs a follow-up cleanup commit. See `git-sync`, "Read state before mutating", for the ordering rule.
 
+## Transform tests (v65+)
+
+A transform test replaces every table the transform reads with a fixture, runs it into a temp table, and checks that output. No real table is read or written.
+
+```bash
+mb transform-test list --transform <id> --profile <n> --json  # --transform is optional
+mb transform-test get <id> --full --profile <n> --json        # --full for inputs/expectations
+mb transform-test create --file ./.scratch/test.json --profile <n> --json
+mb transform-test update <id> --file ./.scratch/patch.json --profile <n> --json
+mb transform-test delete <id> --yes --profile <n>
+mb transform-test run <id> --profile <n> --json               # exits non-zero unless it passes
+```
+
+**`inputs`** — one per table the transform reads, each naming a `table` plus either `format: "sql"` with `sql`, or `format: "rows"` with `columns` (each a `name` and a `cast_type`) and `rows`.
+
+**`cast_type` is a `CAST` target, not a column type**, and the two vocabularies differ per warehouse: MySQL casts to `SIGNED` and reports `INTEGER`; ClickHouse takes `Nullable(Int32)` for a column that is `Int64`. So a body is warehouse-specific — don't copy a `database_type` out of a run result into a `cast_type`, and don't expect one body to run everywhere.
+
+**`expectations`** — `type: "empty"` with the `sql` that must return no rows, or `type: "equals"`, which needs the same `format` split as an input (`"rows"` with `columns`/`rows`, or `"sql"` with a query). An `equals` without a `format` is refused.
+
+**An `empty` query may only name the transform's target table and its declared input tables.** Those are rewritten to the run's temp tables; any other table you name is left exactly as written and reads the real one — the single way a test run can touch production data.
+
+```json
+{
+  "transform_id": 1,
+  "name": "adults only",
+  "inputs": [
+    {
+      "table": { "schema": "public", "name": "people" },
+      "format": "rows",
+      "columns": [
+        { "name": "id", "cast_type": "INTEGER" },
+        { "name": "age", "cast_type": "INTEGER" }
+      ],
+      "rows": [
+        { "id": 1, "age": 30 },
+        { "id": 2, "age": 12 }
+      ]
+    }
+  ],
+  "expectations": [
+    {
+      "type": "equals",
+      "name": "exactly one row, id 1",
+      "format": "rows",
+      "columns": [{ "name": "id", "cast_type": "INTEGER" }],
+      "rows": [{ "id": 1 }]
+    },
+    {
+      "type": "empty",
+      "name": "no null ids",
+      "sql": "SELECT * FROM public.adults WHERE id IS NULL"
+    }
+  ]
+}
+```
+
+Create and update bodies are closed — strip `id`, `entity_id`, `creator_id`, `created_at` and `updated_at` from a `get --full` body before sending it back.
+
 ## Drop the materialized table (keep the transform)
 
 ```bash

package/skill-data/transform-test-plan/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: transform-test-plan
+description: Derive a comprehensive test plan for a transform — the fixture cast, the expectations, hand-derived expected rows, and a coverage matrix — from the model's declared design. Covers input partitioning (zero-case, multiplicity, dirty rows), grain / conservation / recomputation / conformance checks, and known-quirk conventions. Load when the user wants tests planned or written for transforms — "write tests for my transforms", "is my model right", "test plan for this pipeline", "add data quality checks" — whether the model is mid-build or already deployed. The `mb transform-test` command and body shapes live in the `transform` skill; this one decides what to test.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Planning transform tests
+
+Turn a transform into a fixture cast that proves the logic on small known rows, expectations that
+state the model's invariants, and a coverage matrix showing what's checked and what's deliberately
+not. Mechanics — the `inputs`/`expectations` body shape and every `mb transform-test` verb — live in
+the `transform` skill (`mb skills get transform`); load it before authoring, and never restate it
+here.
+
+Every check derives from what the model **declares** — detected from its SQL, confirmed with its
+owner — never from conformance to a modeling doctrine. One plan serves two moments: while the model
+is **built**, checks pin each design decision; once **deployed**, the same SQL screens production
+tables for anomalies.
+
+## Operating rules
+
+- **Detect, then derive.** Classify what the transform is and which conventions it uses (the
+  checklist); derive checks only from that. Star, one-big-table, partial denormalization — all
+  fine; never flag a style.
+- **Judgment calls go through the checklist.** The session's autonomy setting governs which answers
+  you supply yourself and which you bring to the user — it never makes the checklist a formality.
+  Every answer you supply yourself is recorded in the plan as a stated assumption, paired with the
+  named expectation that enforces it — reversing the decision then breaks a test, not a paragraph.
+  And regardless of setting, when genuinely unsure, ask — a wrong-but-confident grain poisons every
+  downstream check.
+- **Expected rows are derived by hand** from the fixture story and business meaning — never captured
+  from the transform's output, which asserts only that the transform equals itself.
+- **Batteries stay off until declared structure switches them on.** No snapshot-density checks
+  without a snapshot, no version-history checks without effective/end/current columns. An empty
+  section beats a speculative one.
+
+## The procedure
+
+1. **Profile the real inputs**: per table, row count; per column, min/max/distinct-count/null
+   incidence; orphan counts across declared links (`mb field summary`, `mb query`). Profiling feeds
+   domains, bounds, null partitions, and key candidates — and every fixture edge cites the real-data
+   condition that warrants it, with its count ("the warehouse has 67 ship-before-order rows").
+2. **Detect.** Read the transform's SQL (`mb transform get <id> --full --json`) for: grain
+   candidates (`GROUP BY` keys, the joins' driving table), join types (orphan handling), correlated
+   aggregates (stored aggregates), `<entity>_<attr>` naming (copies), effective/end/current columns
+   (version history), `now()`/`current_date` (volatile columns). A transform whose grain you cannot
+   state in one phrase is itself a finding — raise it before writing any test.
+3. **Confirm.** Walk [references/checklist.md](references/checklist.md). Three stages: classify the
+   model, per-table declarations, per-column declarations. Each question carries its detection hint;
+   answer autonomously where the hint resolves, ask where it doesn't. In build-along mode these are
+   design questions — treat an undecided answer as a decision to make together, not a blocker.
+4. **Derive.** Route every output column through [references/checks.md](references/checks.md) —
+   declared property → expectation shape, fixture implication, expected-row convention. Read it in
+   full once per plan; it is the plan's content.
+5. **Design the fixture cast**: one small cast per transform (≈5–10 rows per table), human-named
+   rows ("Alice Premium"), every row a named edge — zero-case entities for every outer join and
+   aggregation, ≥2-member groups for every grouping and join, one dirty row per screenable defect,
+   boundary dates. Document it as a table (row → attributes → purpose) in the plan.
+
+   Express the cast as literal rows rather than as a query, so the story stays legible in the test
+   itself; a query is worth it only when the rows are mechanical to generate. A cast is written
+   against one warehouse and does not carry to another.
+
+6. **Hand-derive the expected rows**, arithmetic recorded in the plan (premium: 3 orders / 350.50 /
+   3.0). Every fixture row's fate appears in some expected cell. Pin NULL-vs-0-vs-empty for every
+   zero-case row — that cell is the null policy's only enforcement.
+7. **Author the test.** One test per transform, per coherent story: an `equals` pinning the output,
+   and `empty` expectations stating the invariants that survive a change to the cast.
+
+   Give each expectation a name that states the invariant, because the name is what a
+   failure leads with ("revenue never negative", not "check 3"), and open each `empty` expectation's
+   SQL with a `--` contract comment: the invariant, and the failure modes it catches ("catches both
+   dropped orders and join fan-out").
+
+   Where one invariant applies to several transforms, duplicate the SQL. Nothing is shared between
+   tests, so give each copy its own name and comment rather than one that only makes sense next to
+   its twin.
+
+8. **Emit the coverage matrix** in the plan: rows = output columns with the table's grain; columns =
+   check classes (grain, conservation, recomputation, conformance, domains, referential integrity,
+   temporal, screens); cells name the covering expectation or expected-row cell, or state
+   `gap: <reason>`. Scan shared-attribute columns across transforms for cross-table agreement
+   obligations. Empty cells are honest; silent gaps are not.
+9. **Prove the tests have teeth.** Once per test: corrupt one expected cell, `run`, confirm
+   `cell-mismatches` names exactly that column; revert. Then perturb one input cell and confirm
+   exactly the declared output cells move. Every `empty` expectation passes against an empty output,
+   so a green test can still be vacuous.
+
+## Severity: error, or the tolerated oddity
+
+Every expectation is pass or fail, and one failure fails the run. **error** = forbidden, and it
+becomes an `empty` expectation. There is no warn severity, so **never author an expectation you
+expect to fire**: a permanently red test trains everyone to ignore the result, and a red run gates
+everyone else's work.
+
+A tolerated-but-surfaced oddity — one the owner lives with, like orphan rows or ship-before-order
+dates — gets encoded the two ways that hold: **pin it in the `equals` rows** (an orphan passing
+through with NULLs is a cell in the expected output, so reversing the tolerance breaks the test),
+and **record it in the plan's known-quirks list** with its real-data count, so the tolerance stays a
+conscious choice.
+
+Under budget pressure cut business-rule checks first, then cross-table structure checks; never
+single-column screens (domains, ranges, nulls) — cheapest, and the last line.
+
+## When a check exposes a live bug
+
+Non-negotiable: **never soften the test to green** — expected values state correct behavior; matching
+them to buggy output documents the bug as intended — and **surface the finding with its blast radius
+at both scales**, fixture ("1530.24 of 1600.74 fixture dollars survive") and warehouse ("908 of
+2,050 orders dropped"). What happens next follows the session's terms, not a fixed protocol: propose
+and apply the fix now (when the user wants it or the autonomy setting covers it), or — when the fix
+must wait — hold the correct expectation and record the red in the plan with the minimal fix body.
+A stored test has no red-by-design state, so a deferred
+fix must be visible in the plan or the test reads as broken. Either way, once green the test stays
+as the regression guard.
+
+## When the doctrine doesn't apply
+
+The vocabulary follows Kimball's dimensional modeling (grain, additivity, conformed attributes,
+slowly changing dimensions) — precise, widely understood terms. Real models are Kimball-inspired at
+most; no check may score adherence:
+
+- Full calendar date dimensions are rare. Never demand one; test date _semantics_ — ranges,
+  orderings, volatile derivations.
+- Surrogate keys are doctrine, natural-key joins are practice. Test whichever key the model
+  declares; never flag natural-key joins.
+- "No NULL FKs / no NULL attributes" is doctrine routinely dropped. Null policy is three independent
+  declarations — measures, attributes, FKs — each detected and confirmed, never presumed.
+- One-big-table is legitimate: it still has a grain, its copies still need agreement checks, its
+  functional dependencies still hold.
+- A transform-level `ORDER BY` has no testable effect — output tables carry no row order and the
+  `equals` comparison is a multiset. Flag it as probable dead weight (clustering hints aside); never
+  write an ordering expectation.
+
+## One transform at a time
+
+Each test covers one transform. When the transform under test reads another transform's output,
+that target table is an input like any other: declare it and fake it. Derive those rows from the
+base transform's own expected output, so the two tests tell one story, and note the coupling in both
+plans — changing the base's expected rows means changing this test's input.
+
+## Worked example, condensed
+
+`orders` + `customers` → _enriched_orders_ (order grain; LEFT JOIN attaches `customer_name`,
+`tier`).
+
+Cast, 7 orders: two tiers; Alice and Carol with 2 orders each (multiplicity); two never shipped
+(zero-case for the shipping join); order 106 shipped before ordered (real oddity, count cited);
+order 107's customer_id matches no customer (orphan). Two `rows` inputs, one per source table.
+
+Derived, per catalog: grain uniqueness on `order_id`; row and amount conservation from input to
+output, as scalar subqueries over the target and the seeded input; `tier` domain ⊆ {standard,
+premium}; orphan = keep-with-NULLs → an expected row pinning the NULL pass-through; ship-before-order
+tolerated → the plan's known-quirks list with the warehouse count. The whole output pinned in one
+`equals`, hand-computed, arithmetic in the plan. The inner-vs-LEFT-join bug this cast catches —
+unshipped orders silently dropped from revenue — is what the zero-case rows exist for.
+
+## Don't
+
+- Don't author expectations before loading the `transform` skill — the body shape, the closed
+  create/update contract, and the verb flags live there.
+- Don't capture expected rows from the transform's own output — hand-derive them or they assert
+  nothing.
+- Don't emit checks for structure the model doesn't declare (snapshot density, version history,
+  bridge weights) — an inapplicable battery buries real findings.
+- Don't let a fixture cast go all-clean — no zero-case, no orphan, no dirty row proves the happy
+  path and nothing else; the bugs live in the edges.
+- Don't write an expectation you expect to fail.
+- Don't surface bare check-ids ("per C3…") to the user — name the check in plain words; the ids are
+  for your cross-referencing, not their reading.