@metabase/cli 0.1.6 → 0.1.8-alpha.cleanup-workspaces.75fe1d5

package/dist/{uuid-CMKnS8-z.mjs → uuid-DTdRruiz.mjs}

@@ -1,8 +1,7 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { outputFlags } from "./error-C9S6PN3-.mjs";
-import { defineMetabaseCommand, parseInteger } from "./runtime-Dmv5VtUK.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import { writeJson, writeText } from "./render-CfznwleY.mjs";
+import { outputFlags } from "./error-Br6irjpM.mjs";
+import { defineMetabaseCommand, parseInteger } from "./runtime-DKLBPRhd.mjs";
+import { writeJson, writeText } from "./capabilities-Dj3NgPHg.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 

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

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

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

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

package/dist/values-Bpt6obVW.mjs

@@ -0,0 +1,44 @@
+import "./command-augment-BH9qgQ5u.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-Br6irjpM.mjs";
+import { defineMetabaseCommand } from "./runtime-DKLBPRhd.mjs";
+import { formatScalar, renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { FieldValues, fieldValuesView } from "./field-MGxpNQUH.mjs";
+import { parseId } from "./parse-id-DBwNYb4Y.mjs";
+
+//#region src/commands/field/values.ts
+var values_default = defineMetabaseCommand({
+	meta: {
+		name: "values",
+		description: "Fetch the cached distinct values for a field (FieldValues list)"
+	},
+	capabilities: { minVersion: 58 },
+	args: {
+		...outputFlags,
+		...profileFlag,
+		...connectionFlags,
+		id: {
+			type: "positional",
+			description: "Field id",
+			required: true
+		}
+	},
+	outputSchema: FieldValues,
+	examples: ["mb field values 100", "mb field values 100 --json"],
+	async run({ args, ctx, getClient }) {
+		const id = parseId(args.id);
+		const client = await getClient();
+		const values = await client.requestParsed(FieldValues, `/api/field/${id}/values`);
+		const fieldId = values.field_id ?? id;
+		const count = values.values.length;
+		renderSummary(values, fieldValuesView, () => {
+			if (count === 0) return `Field ${fieldId} has no cached values.`;
+			const more = values.has_more_values === true ? " (more available; rescan for the full set)" : "";
+			const header = `Field ${fieldId} has ${count} cached value${count === 1 ? "" : "s"}${more}:`;
+			const lines = values.values.map((row) => `  ${formatScalar(row[0])}`);
+			return [header, ...lines].join("\n");
+		}, ctx);
+	}
+});
+
+//#endregion
+export { values_default as default };

package/dist/{verify-D5YtTqqp.mjs → verify-COt2q73-.mjs}

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

package/dist/{wait-Bv3Tsnv4.mjs → wait-DoKPlspq.mjs}

@@ -1,11 +1,10 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-C9S6PN3-.mjs";
-import { defineMetabaseCommand } from "./runtime-Dmv5VtUK.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import { renderItem } from "./render-CfznwleY.mjs";
-import { parseId } from "./parse-id-lk_K-CEF.mjs";
-import { SyncTaskOrIdle, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-Cooi0lQV.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DHKDpCiq.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-Br6irjpM.mjs";
+import { defineMetabaseCommand } from "./runtime-DKLBPRhd.mjs";
+import { renderSummary } from "./capabilities-Dj3NgPHg.mjs";
+import { parseId } from "./parse-id-DBwNYb4Y.mjs";
+import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-DOvUDrgL.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DWkVceIk.mjs";
 
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;
@@ -45,10 +44,10 @@ var wait_default = defineMetabaseCommand({
 		});
 		if (final === null) {
 			const idle = { status: "idle" };
-			renderItem(idle, syncTaskIdleView, ctx);
+			renderSummary(idle, syncTaskIdleView, "No git-sync task is running.", ctx);
 			return;
 		}
-		renderItem(final, syncTaskView, ctx);
+		renderSummary(final, syncTaskView, formatSyncTask(final), ctx);
 		throwIfFailedTask(final, "task");
 	}
 });

package/dist/{wait-flags-Dzq9BGQY.mjs → wait-flags-D1jNm0JK.mjs}

@@ -1,5 +1,5 @@
-import { parseId } from "./parse-id-lk_K-CEF.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DHKDpCiq.mjs";
+import { parseId } from "./parse-id-DBwNYb4Y.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DWkVceIk.mjs";
 
 //#region src/commands/wait-flags.ts
 const waitScheduleFlags = {

package/package.json

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

package/skill-data/core/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: core
-description: Drive a Metabase instance from the terminal via the `mb` CLI — auth, databases, cards, dashboards, collections, transforms, queries, search, git-sync, Enterprise workspaces. Use for any `mb <verb>` task.
+description: Drive a Metabase instance from the terminal via the `mb` CLI — auth, databases, cards, dashboards, collections, transforms, queries, search, git-sync. Use for any `mb <verb>` task.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
 # metabase-cli (core)
 
-The official Metabase CLI (`mb`) drives a Metabase instance over its REST API. It covers auth, list/get/create/update/delete on every resource, query and transform execution, content search, git-sync (representations ↔ instance), Enterprise workspaces, and entity-id translation.
+The official Metabase CLI (`mb`) drives a Metabase instance over its REST API. It covers auth, list/get/create/update/delete on every resource, query and transform execution, content search, git-sync (representations ↔ instance), and entity-id translation.
 
 Top-level command groups (run `mb <group> --help` to discover verbs):
 
 ```
 auth | db | table | field | query | card | dashboard | snippet | segment | measure | collection
-transform | transform-job | setting | search | git-sync | workspace | setup | eid | uuid | upgrade | skills
+transform | transform-job | setting | search | git-sync | setup | eid | uuid | upgrade | skills
 ```
 
 The patterns below — auth, flag conventions, output flags, body input — apply across **every** group. Per-command flags, examples, and output schemas live in `mb __manifest` (see below). A few flows have their own specialized skills; load them on demand (see "Specialized skills"). Authoring any query body (cards, transforms, measures, segments, ad-hoc `mb query`) is one — load `mbql` whenever you build MBQL by hand.
@@ -21,8 +21,6 @@ The patterns below — auth, flag conventions, output flags, body input — appl
 
 **The agent does not log in for the user.** Authentication is the human's job — they pick the base URL, paste credentials, and store them as a named profile. The agent's role is to _check_ what profiles exist, _ask_ which to use, and pass `--profile <name>` through every command.
 
-**The one exception** is a freshly bootstrapped workspace child: its API key is minted by the parent the human already authorized, so the agent reads it via `mb workspace credentials <ws-id>` and saves it with `auth login` — piping the key on **stdin** (`printf '%s' "$KEY" | mb auth login …`), never on an `--api-key` flag (the CLI rejects the flag form). See the `workspace` skill, step 4.
-
 ### Discover what's already configured
 
 ```bash
@@ -35,17 +33,7 @@ mb auth status --profile <name> --json   # → status of a specific profile
 
 ### Pick the profile to use
 
-If exactly one profile is configured and the user's intent doesn't disambiguate, use it. If multiple profiles exist and the user hasn't named one, ask via `AskUserQuestion`, presenting the names from `auth list`. Once a name is established, pass `--profile <name>` to **every** subsequent command. Profile names are arbitrary local labels — `prod`, `staging`, the workspace name — let the user pick.
-
-### Other secrets (license, warehouse passwords)
-
-Same rule: the human runs the storing command. To check whether a license is present:
-
-```bash
-mb workspace license status --json   # → {present: bool}
-```
-
-If `present: false`, ask the user to run `echo "<your-token>" | mb workspace license set` from their terminal — don't paste the token in chat.
+If exactly one profile is configured and the user's intent doesn't disambiguate, use it. If multiple profiles exist and the user hasn't named one, ask via `AskUserQuestion`, presenting the names from `auth list`. Once a name is established, pass `--profile <name>` to **every** subsequent command. Profile names are arbitrary local labels — `prod`, `staging` — let the user pick.
 
 ## Flag conventions
 
@@ -56,21 +44,21 @@ If `present: false`, ask the user to run `echo "<your-token>" | mb workspace lic
 ❌ mb --profile prod table list           # → error: "Unknown command prod"
 ```
 
-`--profile` attaches **after** the full verb chain (`table list`, `card get`, `workspace start`).
+`--profile` attaches **after** the full verb chain (`table list`, `card get`, `git-sync export`).
 
 ### `--wait` for async operations
 
-`workspace start`, `workspace database provision`, `transform run`, and similar async verbs return immediately by default. Pass `--wait` for any interactive flow where the next step depends on completion. Without it you'll race the operation and see "not ready" / `state: starting` / transient connection refusals.
+`transform run`, `git-sync import`, and similar async verbs return immediately by default. Pass `--wait` for any interactive flow where the next step depends on completion. Without it you'll race the operation and see "not ready" / transient connection refusals.
 
 ### Some outputs are JSON envelopes, not bare strings
 
-A handful of "lookup" verbs return a JSON object even when you only want a single field. `mb workspace url <id>` returns `{"workspace_id": ..., "url": "http://..."}`, not `"http://..."`. Don't drop them raw into another flag — extract:
+A handful of "lookup" verbs return a JSON object even when you only want a single field. `mb setting get <key>` returns `{"key": "...", "value": ...}`, not the bare value. Don't drop them raw into another flag — extract:
 
 ```bash
-WS_URL=$(mb workspace url <id> --json | jq -r '.url')
+VALUE=$(mb setting get <key> --json | jq -r '.value')
 ```
 
-If you find yourself writing `--url $(mb ...)` and the receiving command rejects it with "URL must start with http://", this is what happened.
+If you find yourself piping a `--json` envelope straight into another flag and the receiving command rejects it, this is what happened.
 
 ## Output
 
@@ -78,7 +66,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 (compact projection is the default for list/get).
-- `--fields a,b.c.d` — project specific dot-paths. Mutually exclusive with `--full`.
+- `--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` (the projection runs per row) — `data.id` and `data[].id` both fail with `unknown field path: "data.id"`. On single-object verbs the path is root-relative: `--fields id,name,display` on `card get`, and `--fields data.rows` on `mb query` (whose `data` is an object, not an array).
 - `--max-bytes <n>` — cap **list** output size (drops trailing items, sets `truncated`). Default 65 536; `0` disables. Single-item commands (`get`, `metadata`) never truncate — they emit a stderr advisory when over the cap.
 
 List envelope shape:
@@ -144,7 +132,7 @@ Routine verb shapes (list / get / create / update), every flag, and output JSON
 - **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact) or use `table fields <id>` (list envelope). `table metadata <id>` adds FKs + dimensions (heavier). `table update` patches table-level metadata only; physical columns aren't editable here.
 - **field has no `list`.** Fields are per-table — get them via `table get <id> --include fields`. Never enumerate fields across a whole db (context blow-up). `field summary` is live cardinality `{field_id, count, distincts}`; `field values` is the cached distinct set (`has_more_values: true` ⇒ truncated cache). `field update` patches metadata only; `base_type` isn't editable.
 - **card.** `dataset_query` is the **flat** `mbql/query` value, not a legacy `{type:"query",query:…}` envelope (→ `mbql` skill). `--export-format csv|xlsx` streams the raw export (pipe to a file), bypassing the JSON envelope. `archive` is the only delete; unarchive with `update --body '{"archived":false}'`. `visualization_settings` keys are scoped by `display` and aren't pre-flighted — see the `viz` skill.
-- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; use negative ids for new cards). `create`/`update` pre-flight every positive `card_id` against live server state and exit **2** with `{ok:false,errors:[…]}` on a bad ref — non-bypassable (no `--skip-validate`). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them.
+- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; use negative ids for new cards). `create` accepts the **same** `dashcards` array in its initial body, so you can lay out the whole dashboard in one call — negative ids for new cards, and `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create`/`update` pre-flight every positive `card_id` against live server state and exit **2** with `{ok:false,errors:[…]}` on a bad ref — non-bypassable (no `--skip-validate`). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them.
 - **snippet `--archived` is a swap, not a union** — list returns _either_ active _or_ archived rows, never both. (Same shape for `--filter archived` on dashboard/collection.)
 - **segment / measure** `update` and `archive` require a non-blank `revision_message` (audit-logged); the CLI does not synthesize it on `update`. `archive` defaults to `"Archived via mb CLI"` — override with `--revision-message`. `definition` is a flat MBQL clause (→ `mbql` skill): segment = a filter, measure = exactly one aggregation.
 - **collection `<ref>`** accepts four forms only — positive int, `root`, `trash`, or a 21-char entity_id — anything else is a client-side `ConfigError`. `collection items` auto-paginates (cap with `--limit`, which then omits `total`). `collection tree` is **JSON-only** — `--format text` is rejected.
@@ -157,11 +145,10 @@ Routine verb shapes (list / get / create / update), every flag, and output JSON
 
 ## Specialized skills (load on demand)
 
-This core file is enough for any single-command task. Load the relevant skill **proactively** when intent matches — don't wing an MBQL body, the workspace lifecycle, a transform body, or the git-sync workflow from this overview alone. Load each via `mb skills get <name>`.
+This core file is enough for any single-command task. Load the relevant skill **proactively** when intent matches — don't wing an MBQL body, a transform body, or the git-sync workflow from this overview alone. Load each via `mb skills get <name>`.
 
 - **`mbql`** — authoring or fixing any MBQL query body: `mb query`, a card `dataset_query`, a transform `source.query`, a measure/segment `definition`, "aggregate and group by", reading `--dry-run` errors. The query-body reference.
 - **`viz`** — choosing a card's `display` and authoring `visualization_settings`: "make it a bar chart", "set the pie dimension/metric", "format this column as currency", "the card renders as a table instead of a chart". The presentation counterpart to `mbql`.
-- **`workspace`** — "spin up a workspace", "provision", "start a local Metabase against my prod", anything `mb workspace …`. **Mandatory** before `workspace start` — ask the user about Remote Sync up front (the bind mount is create-time only).
 - **`transform`** — "create a transform", "run a transform", authoring transform body JSON, run inspection.
 - **`git-sync`** — "import the latest changes", "export to git", "git sync", "dirty check", "stash before pulling".
 
@@ -169,9 +156,9 @@ If a task spans more than one, load each. Specialized skills assume the conventi
 
 ## Don't
 
-- **Don't run `mb auth login` for the user** — authentication is theirs (see §Auth). The only exception is saving a workspace child's credentials, and even there pipe the key on stdin.
-- Don't paste credentials, license tokens, or warehouse passwords in chat. Have the user run the storing command.
+- **Don't run `mb auth login` for the user** — authentication is theirs (see §Auth).
+- Don't paste credentials or warehouse passwords in chat. Have the user run the storing command.
 - Don't put `--profile` before the verb chain — the CLI parses it as a subcommand and errors out.
-- Don't omit `--wait` on `workspace start` / `transform run` / `workspace database provision` for interactive flows; the next step will race the operation.
+- Don't omit `--wait` on `transform run` / `git-sync import` for interactive flows; the next step will race the operation.
 - Don't drop a JSON-envelope verb's output raw into another flag. Extract with `--json | jq -r '.<field>'`.
 - Don't add a third-party HTTP library or shell into `curl` against `/api/...` when a `mb <verb>` exists — that bypasses retries, schema validation, and credential redaction.

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

@@ -1,6 +1,6 @@
 ---
 name: git-sync
-description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections) between an instance and a git remote via `mb git-sync …` — status, dirty / has-remote-changes checks, import (with first-fresh-workspace exception), export (with branch guard + working-tree drift), branches, stash, add/remove a collection from sync. Load when the user wants to "import the latest changes", "export to git", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …`.
+description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections) between an instance and a git remote via `mb git-sync …` — status, dirty / has-remote-changes checks, import, export (with branch guard), branches, stash, add/remove a collection from sync. Load when the user wants to "import the latest changes", "export to git", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -75,25 +75,6 @@ Workflow:
 2. `git-sync has-remote-changes` — confirm there's actually something to import.
 3. `git-sync import --branch <branch>` — runs to terminal status by default.
 
-### First import on a fresh workspace
-
-After `workspace start --repo …` brings up a brand-new workspace, the repo content **must be applied** before any other work — without it the instance has none of the repo content and subsequent edits will diverge from what's on disk.
-
-The container runs a boot-time auto-import on first start, so in most cases the import has already completed by the time `workspace start --wait` returns. Check `git-sync status` first — if `current_task.sync_task_type == "import"` with `status == "successful"` and `.branch` matches the host's branch, you're done; skip the explicit call (it's a wasted round-trip). Only run the explicit `git-sync import` when the auto-import hasn't landed yet.
-
-When you do need the explicit import, the first one on a fresh instance can report `status: conflict` (typically `conflicts: ["Transforms"]`) even when nothing is dirty — the boot-time auto-import sometimes leaves a stale task record that the first explicit import collides with. Retry the same command once; the second call usually succeeds. If it keeps reporting conflict, `git-sync import --force` is safe in this specific case because the workspace is empty — there's no instance-side work for `--force` to discard. (This is a narrow exception to the usual "confirm with the user before `--force`" rule.)
-
-```bash
-HOST_BRANCH=$(git -C <repo-path> symbolic-ref --short HEAD)
-SYNC_STATUS=$(mb git-sync status --profile <ws-name> --json)
-if ! echo "$SYNC_STATUS" | jq -e --arg b "$HOST_BRANCH" \
-     '.current_task.sync_task_type == "import" and .current_task.status == "successful" and (.branch == $b)' >/dev/null; then
-  mb git-sync import --branch "$HOST_BRANCH" --profile <ws-name> --json \
-    || mb git-sync import --branch "$HOST_BRANCH" --profile <ws-name> --json \
-    || mb git-sync import --branch "$HOST_BRANCH" --force --profile <ws-name> --json
-fi
-```
-
 ## Export (instance → remote)
 
 ```bash
@@ -111,61 +92,26 @@ Pushes Metabase-side changes back to the configured remote. `-m` is the commit m
 
 Workflow:
 
-1. **Branch guard** (below) — confirm the workspace isn't tracking `main`/`master`, or that the user has explicitly accepted exporting to it.
+1. **Branch guard** (below) — confirm the instance isn't tracking `main`/`master`, or that the user has explicitly accepted exporting to it.
 2. `git-sync is-dirty` — confirm there's something to export.
 3. `git-sync export -m "..."` — pushes and polls.
 4. (Optional) `git-sync status` — verify `dirty: false` after.
-5. **Working-tree drift** (below) — if this is a `--repo` bind-mount workspace, the host repo's working tree + index will lag behind the new HEAD. Surface this and offer to realign.
 
 ### Branch guard: don't export to main/master without confirmation
 
-Workspace work is conventionally done on a feature branch — exporting to `main` (or `master`) commits team-shared content directly. Before `git-sync export`, check the tracked branch and if it's `main`/`master`, ask the user whether to switch first.
-
-Reading the current branch:
+Sync work is conventionally done on a feature branch — exporting to `main` (or `master`) commits team-shared content directly. Before `git-sync export`, check the tracked branch and if it's `main`/`master`, ask the user whether to switch first.
 
-- For a `--repo` bind-mount workspace, `git -C <repo-path> symbolic-ref --short HEAD` is the most reliable read — that's what the workspace's `remote-sync-branch` was bound to at start time.
-- Otherwise: `mb git-sync status --profile <n> --json | jq -r '.branch'`.
+Read the current branch with `mb git-sync status --profile <n> --json | jq -r '.branch'`.
 
 If the branch is `main` or `master`, prompt with `AskUserQuestion`:
 
-> "The workspace is tracking `<branch>` — exporting commits straight to it. Switch to a feature branch first?"
+> "The instance is tracking `<branch>` — exporting commits straight to it. Switch to a feature branch first?"
 >
-> 1. **Create a feature branch via the workspace** — agent suggests a name (e.g., `agent/<task>`); run `mb git-sync create-branch <name> --profile <n>`. This exports current dirty state to the new branch and switches the workspace's tracked branch to it; subsequent `git-sync export` calls go to that branch.
-> 2. **Switch the host's branch first (bind-mount workspaces)** — `git -C <repo> checkout -b <name>` on the host, then pass `--branch <name>` on the next `git-sync export` so the export targets the new branch (the workspace's `remote-sync-branch` setting won't auto-update from a host-side checkout).
-> 3. **Proceed on `main`/`master`** — explicitly accepted; surface the resulting commit (`git -C <repo> log --oneline -1`) afterwards so the user can amend or revert.
+> 1. **Create a feature branch** — agent suggests a name (e.g., `agent/<task>`); run `mb git-sync create-branch <name> --profile <n>`. This exports current dirty state to the new branch and switches the instance's tracked branch to it; subsequent `git-sync export` calls go to that branch.
+> 2. **Proceed on `main`/`master`** — explicitly accepted.
 
 Skip the prompt only if the user's instructions already specified the branch (e.g., they explicitly said "export to main" or named a feature branch). Don't silently default to whatever `remote-sync-branch` happens to point at.
 
-### Post-export: working-tree drift on `--repo` bind-mount workspaces
-
-When the workspace exports against a host bind mount, the in-container serializer writes the new commit object directly into the bind-mounted `.git/` (creating tree/blob objects and advancing the branch ref) but **does not update the host's working tree or index**. After a successful export, the host repo state is:
-
-- HEAD: the new export commit.
-- Index: still matches the _previous_ HEAD (whatever the user had staged before).
-- Working tree: still matches the _previous_ HEAD.
-
-`git status` then shows "Changes to be committed" that look like the export's content reverting back — purely a display artifact, not an actual revert. The container does this on purpose to avoid clobbering work-in-progress on the host. **Realigning is _applying_ the new HEAD's content to your worktree, not discarding work** — the new commit was written by the exporter, not by your local edits, and your tree/index are stale relative to the new HEAD until you realign.
-
-**Surface this to the user** after an export against a `--repo` workspace — don't leave them staring at a confusing `git status`. Offer to realign.
-
-**Prefer `git restore` over `git reset --hard`.** When the only "changes" are the drift artifact (no real local edits), `git restore` does the same job and isn't classified as a destructive operation by Claude Code's permission system — `git reset --hard` is, and gets blocked even after a user-confirmation dialog:
-
-```bash
-git -C <repo> restore --staged --worktree .   # non-destructive; aligns index + working tree to HEAD
-```
-
-This is the right default after a `git-sync export` realignment when the user had nothing else staged. If `git status` shows a mix of drift artifacts and real pending work, fall back to the stash sequence:
-
-```bash
-git -C <repo> stash --include-untracked
-git -C <repo> restore --staged --worktree .
-git -C <repo> stash pop
-```
-
-`git reset --hard HEAD` is the canonical equivalent and still valid — but **confirm with the user** before running it, and expect Claude Code to gate it as destructive even after the dialog. `git restore --staged --worktree .` produces the same end-state with less friction.
-
-Or pull in the new files selectively with `git -C <repo> checkout HEAD -- <path>`. Quick check that this is what you're seeing: `git -C <repo> diff --cached HEAD~1 --stat` returns empty (the index matches the parent commit, not the new HEAD).
-
 ## Branches
 
 ```bash
@@ -191,6 +137,5 @@ Use `wait` after `import --no-wait` / `export --no-wait`. Use `cancel-task` if a
 - Don't drive `git-sync` against a Metabase instance that doesn't have remote-sync configured — every verb returns an error pointing at the missing `remote-sync-*` settings. To check: `mb setting get remote-sync-url --profile <n> --json`.
 - Don't author content directly via `card create` / `transform create` and then assume `git-sync export` will commit it cleanly — the instance and repo can drift if you mix direct API writes with sync-tracked changes. If you do, follow direct writes immediately with `git-sync export -m "..."` to keep them in step.
 - Don't omit `-m` on `export` if the user wants a meaningful commit message — the default server-generated message is generic.
-- Don't `git-sync export` to `main`/`master` without explicit user confirmation — workspace work is conventionally on a feature branch. See "Branch guard" above.
-- Don't pretend the host's `git status` is clean after `git-sync export` against a `--repo` bind mount — the export advances HEAD but leaves the working tree + index behind. See "Working-tree drift" above.
+- Don't `git-sync export` to `main`/`master` without explicit user confirmation — sync work is conventionally on a feature branch. See "Branch guard" above.
 - Don't reach for `mb setting set` to mark a collection as remote-synced — that endpoint writes single-key settings, not the bulk `collections` map. Use `mb git-sync add-collection <id>` / `mb git-sync remove-collection <id>` (see "Adding / removing a directory (collection) to sync" above), and remember the toggle cascades to descendants.

package/skill-data/mbql/SKILL.md

@@ -87,6 +87,8 @@ mb query --file q.json --profile <n> --json                     # 3. validate +
 
 `path` is a JSON Pointer into the body (`/stages/0/aggregation/0`); `message` is the validator error. Exit codes: `0` valid + ran, `2` validation failed / malformed body, `1` server-side error after a valid pre-flight.
 
+A successful run emits the **full `/api/dataset` envelope** — `data.rows`, `data.cols`, plus heavy `data.results_metadata` and per-column fingerprints. For ad-hoc exploration project `--fields data.rows` (add `data.cols` if you need column names); without it even a few rows render as hundreds of lines of metadata. (`mb query` also runs a **native** body — `{database, type:"native", native:{query:"SELECT …"}}` — which skips pre-flight and is the quickest way to eyeball raw warehouse data; same `--fields data.rows` advice applies.)
+
 `--skip-validate` bypasses the pre-flight and sends as-is — use only when the bundled schema disagrees with what the server actually accepts (drift / false negative). Mutually exclusive with `--dry-run`. The same flag exists on `card create/update` and `transform create/update`.
 
 ## Where MBQL 5 is consumed

package/skill-data/transform/SKILL.md

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