@metabase/cli 0.1.4 → 0.1.6

package/dist/verify-D5YtTqqp.mjs

@@ -0,0 +1,79 @@
+import { MetabaseError, NetworkError, TimeoutError, errorMessage } from "./command-augment-BH9qgQ5u.mjs";
+import { HttpError, createClient, probeServer } from "./runtime-Dmv5VtUK.mjs";
+import { z } from "zod";
+
+//#region src/domain/user.ts
+const CurrentUser = z.object({
+	id: z.number().int(),
+	email: z.email(),
+	common_name: z.string(),
+	is_superuser: z.boolean()
+}).loose();
+const CurrentUserCompact = CurrentUser.pick({
+	id: true,
+	email: true,
+	common_name: true,
+	is_superuser: true
+}).strip();
+
+//#endregion
+//#region src/core/auth/verify.ts
+const VERIFY_TIMEOUT_MS = 15e3;
+const USER_PATH = "/api/user/current";
+async function verifyAndProbe(url, apiKey) {
+	const client = createClient({
+		url,
+		apiKey
+	});
+	const userPromise = client.requestParsed(CurrentUser, USER_PATH, {
+		timeoutMs: VERIFY_TIMEOUT_MS,
+		retries: 0
+	});
+	const serverPromise = probeServer(client);
+	const [userResult, serverResult] = await Promise.allSettled([userPromise, serverPromise]);
+	if (userResult.status === "rejected") return failure(userResult.reason, "user");
+	if (serverResult.status === "rejected") return failure(serverResult.reason, "server");
+	const probed = {
+		id: userResult.value.id,
+		name: userResult.value.common_name,
+		isAdmin: userResult.value.is_superuser
+	};
+	return {
+		ok: true,
+		user: probed,
+		server: serverResult.value
+	};
+}
+function failure(error, which) {
+	if (error instanceof HttpError) {
+		const kind = error.status === 401 || error.status === 403 ? "auth" : "server";
+		return {
+			ok: false,
+			which,
+			kind,
+			status: error.status,
+			message: error.userMessage
+		};
+	}
+	if (error instanceof NetworkError || error instanceof TimeoutError) return {
+		ok: false,
+		which,
+		kind: "network",
+		message: error.userMessage
+	};
+	if (error instanceof MetabaseError) return {
+		ok: false,
+		which,
+		kind: "server",
+		message: error.userMessage
+	};
+	return {
+		ok: false,
+		which,
+		kind: "server",
+		message: errorMessage(error)
+	};
+}
+
+//#endregion
+export { verifyAndProbe };

package/dist/{wait-CeUPCgdc.mjs → wait-8yV9_WIo.mjs}

@@ -1,5 +1,5 @@
-import { pollUntil } from "./poll-BCnrcUVf.mjs";
-import { Workspace } from "./workspace-C5q4nbpY.mjs";
+import { pollUntil } from "./poll-DHKDpCiq.mjs";
+import { Workspace } from "./workspace-BBXJczJK.mjs";
 
 //#region src/commands/workspace/database/wait.ts
 async function waitForDatabaseProvisioned(client, workspaceId, databaseId, schedule) {

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

@@ -1,11 +1,11 @@
-import "./package-D-aVYFKM.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { renderItem } from "./render-DuoDUTVL.mjs";
-import "./predicates-CGO17Q15.mjs";
-import { connectionFlags, defineMetabaseCommand, outputFlags, profileFlag } from "./runtime-Br8L4NPm.mjs";
-import { parseId } from "./parse-id-B3B-0hUA.mjs";
-import { SyncTaskOrIdle, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-0b1V6G-8.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-BCnrcUVf.mjs";
+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";
 
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;
@@ -14,6 +14,10 @@ var wait_default = defineMetabaseCommand({
 		name: "wait",
 		description: "Poll the current git-sync task until it reaches a terminal status"
 	},
+	capabilities: {
+		minVersion: 60,
+		tokenFeature: "remote_sync"
+	},
 	args: {
 		...outputFlags,
 		...profileFlag,

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

@@ -1,13 +1,8 @@
-import { parseId } from "./parse-id-B3B-0hUA.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-BCnrcUVf.mjs";
+import { parseId } from "./parse-id-lk_K-CEF.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DHKDpCiq.mjs";
 
 //#region src/commands/wait-flags.ts
-const waitFlags = {
-	wait: {
-		type: "boolean",
-		description: "Poll until the operation reaches a terminal state",
-		default: false
-	},
+const waitScheduleFlags = {
 	timeout: {
 		type: "string",
 		description: "Polling timeout in ms (used with --wait)",
@@ -19,6 +14,22 @@ const waitFlags = {
 		default: String(DEFAULT_INTERVAL_MS)
 	}
 };
+const waitFlags = {
+	wait: {
+		type: "boolean",
+		description: "Poll until the operation reaches a terminal state",
+		default: false
+	},
+	...waitScheduleFlags
+};
+const gitSyncWaitFlags = {
+	wait: {
+		type: "boolean",
+		description: "Poll the resulting task until it reaches a terminal status (default: true; pass --no-wait to fire-and-forget)",
+		default: true
+	},
+	...waitScheduleFlags
+};
 function parseWaitFlags(args) {
 	const interval = args.interval ?? String(DEFAULT_INTERVAL_MS);
 	const timeout = args.timeout ?? String(DEFAULT_TIMEOUT_MS);
@@ -32,4 +43,4 @@ function parseWaitFlags(args) {
 }
 
 //#endregion
-export { parseWaitFlags, waitFlags };
+export { gitSyncWaitFlags, parseWaitFlags, waitFlags };

package/dist/workspace-CKLZrR7l.mjs

@@ -0,0 +1,26 @@
+import { defineCommand } from "citty";
+
+//#region src/commands/workspace/index.ts
+var workspace_default = defineCommand({
+	meta: {
+		name: "workspace",
+		alias: "workspaces",
+		description: "Manage Metabase workspaces (workspace-manager)"
+	},
+	subCommands: {
+		list: () => import("./list-zSO0DMw-.mjs").then((mod) => mod.default),
+		create: () => import("./create-CHF313Qg.mjs").then((mod) => mod.default),
+		database: () => import("./database-CIXwHKjK.mjs").then((mod) => mod.default),
+		start: () => import("./start-3PX3ahjT.mjs").then((mod) => mod.default),
+		stop: () => import("./stop-CQ0XGrN8.mjs").then((mod) => mod.default),
+		delete: () => import("./delete-CM3jnAeQ.mjs").then((mod) => mod.default),
+		logs: () => import("./logs-CywPikkL.mjs").then((mod) => mod.default),
+		url: () => import("./url-DWaT6WIZ.mjs").then((mod) => mod.default),
+		credentials: () => import("./credentials-dzeq7ckm.mjs").then((mod) => mod.default),
+		ps: () => import("./ps-DEroLgbI.mjs").then((mod) => mod.default),
+		license: () => import("./license-Dxarh-gG.mjs").then((mod) => mod.default)
+	}
+});
+
+//#endregion
+export { workspace_default as default };

package/dist/{workspace-credentials-Cctumbru.mjs → workspace-credentials-BXpABsNZ.mjs}

@@ -1,47 +1,8 @@
-import { ConfigError, ValidationError, errorMessage } from "./predicates-CGO17Q15.mjs";
+import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
+import { parseYaml, stringifyYaml } from "./yaml-YTQiYJ9s.mjs";
 import { z } from "zod";
 import { randomBytes } from "node:crypto";
-import { YAMLParseError, parse, stringify } from "yaml";
 
-//#region src/runtime/yaml.ts
-function parseYaml(input, schema, opts = {}) {
-	const result = parseYamlResult(input, schema, opts);
-	if (!result.ok) throw result.error;
-	return result.value;
-}
-function parseYamlResult(input, schema, opts = {}) {
-	const sourcePrefix = opts.source ? `${opts.source}: ` : "";
-	let raw;
-	try {
-		raw = parse(input);
-	} catch (error) {
-		if (error instanceof YAMLParseError) return {
-			ok: false,
-			error: new ConfigError(`${sourcePrefix}invalid YAML: ${error.message}`)
-		};
-		return {
-			ok: false,
-			error: new ConfigError(`${sourcePrefix}invalid YAML: ${errorMessage(error)}`)
-		};
-	}
-	const parsed = schema.safeParse(raw);
-	if (!parsed.success) return {
-		ok: false,
-		error: new ValidationError(`${sourcePrefix}value did not match expected schema`, {
-			source: opts.source ?? "<input>",
-			zodIssues: parsed.error.issues
-		})
-	};
-	return {
-		ok: true,
-		value: parsed.data
-	};
-}
-function stringifyYaml(value) {
-	return stringify(value, { lineWidth: 0 });
-}
-
-//#endregion
 //#region src/core/workspace-credentials.ts
 const API_KEY_NAME = "Workspace API Key";
 const API_KEY_GROUP = "admin";

package/dist/yaml-YTQiYJ9s.mjs

@@ -0,0 +1,43 @@
+import { ConfigError, ValidationError, errorMessage } from "./command-augment-BH9qgQ5u.mjs";
+import { YAMLParseError, parse, stringify } from "yaml";
+
+//#region src/runtime/yaml.ts
+function parseYaml(input, schema, opts = {}) {
+	const result = parseYamlResult(input, schema, opts);
+	if (!result.ok) throw result.error;
+	return result.value;
+}
+function parseYamlResult(input, schema, opts = {}) {
+	const sourcePrefix = opts.source ? `${opts.source}: ` : "";
+	let raw;
+	try {
+		raw = parse(input);
+	} catch (error) {
+		if (error instanceof YAMLParseError) return {
+			ok: false,
+			error: new ConfigError(`${sourcePrefix}invalid YAML: ${error.message}`)
+		};
+		return {
+			ok: false,
+			error: new ConfigError(`${sourcePrefix}invalid YAML: ${errorMessage(error)}`)
+		};
+	}
+	const parsed = schema.safeParse(raw);
+	if (!parsed.success) return {
+		ok: false,
+		error: new ValidationError(`${sourcePrefix}value did not match expected schema`, {
+			source: opts.source ?? "<input>",
+			zodIssues: parsed.error.issues
+		})
+	};
+	return {
+		ok: true,
+		value: parsed.data
+	};
+}
+function stringifyYaml(value) {
+	return stringify(value, { lineWidth: 0 });
+}
+
+//#endregion
+export { parseYaml, parseYamlResult, stringifyYaml };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metabase/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Metabase CLI",
   "license": "AGPL-3.0",
   "repository": {
@@ -11,7 +11,10 @@
     "mb": "./dist/cli.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "skill-data",
+    ".claude-plugin"
   ],
   "type": "module",
   "publishConfig": {
@@ -29,6 +32,7 @@
     "e2e:up": "docker compose -f tests/e2e/docker-compose.yml up -d --wait",
     "e2e:down": "docker compose -f tests/e2e/docker-compose.yml down -v",
     "e2e:bootstrap": "bun tests/e2e/setup/bootstrap.ts",
+    "e2e:matrix": "bun scripts/e2e-matrix.ts",
     "e2e:logs": "docker compose -f tests/e2e/docker-compose.yml logs -f metabase",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint",

package/skill-data/core/SKILL.md

@@ -0,0 +1,177 @@
+---
+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.
+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.
+
+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
+```
+
+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.
+
+## Auth & profiles
+
+**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
+mb auth list --json                      # → {data: [{profile, url, authenticated, status, …}], returned, total}
+mb auth status --json                    # → {profile, present, url} for the default profile
+mb auth status --profile <name> --json   # → status of a specific profile
+```
+
+`auth list` is the primary enumeration path — one call returns every configured profile with sanitized URL, an `authenticated` flag, and a probe `status` (`ok` / `auth-failed` / `network-error` / `server-error` / `not-probed`). Use it before asking the user which profile to pick. If it returns an empty `data: []`, ask the user to run `mb auth login` themselves (see the policy above) and tell you the profile name. `auth status` is a single-profile health probe when you already know the name.
+
+### 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.
+
+## Flag conventions
+
+### `--profile` is per-subcommand, not global
+
+```bash
+✅ mb table list --profile prod --json
+❌ mb --profile prod table list           # → error: "Unknown command prod"
+```
+
+`--profile` attaches **after** the full verb chain (`table list`, `card get`, `workspace start`).
+
+### `--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.
+
+### 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:
+
+```bash
+WS_URL=$(mb workspace url <id> --json | jq -r '.url')
+```
+
+If you find yourself writing `--url $(mb ...)` and the receiving command rejects it with "URL must start with http://", this is what happened.
+
+## Output
+
+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`.
+- `--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:
+
+```json
+{
+  "data": [
+    /* items */
+  ],
+  "returned": 10,
+  "total": 42,
+  "limit": 50,
+  "truncated": false
+}
+```
+
+The compact item projection is the agent-facing contract — add `--full` for all Metabase fields. `total` is best-effort and may be `null` (empty / permissions-filtered collections, or `--limit` early-stop); use `returned` for the count you got and `data.length` for the rendered slice.
+
+## Body input (create / update / run)
+
+Verbs that take a payload accept it from one of four sources, **first non-empty wins**:
+
+1. `--body '<inline JSON>'`
+2. `--file <path>` — JSON file
+3. stdin (auto-detected when piped, or explicit `--stdin` where supported)
+4. positional argument
+
+Picking exactly one is required; passing two of `--body` + `--file` + `--stdin` is rejected with a `ConfigError`.
+
+```bash
+cat > /tmp/body.json <<'EOF'
+{ ... }
+EOF
+mb <noun> create --file /tmp/body.json --profile <n> --json
+```
+
+Single-quoted `'EOF'` prevents the shell from interpolating `$vars` inside the JSON.
+
+## Discover the full surface: `mb __manifest`
+
+For the canonical, machine-readable inventory of every command — name, description, per-command `details`, examples, every flag with type and default, and the output JSON Schema — run:
+
+```bash
+mb __manifest
+```
+
+The leading `__` hides it from `--help`, but it's stable. Reach for it instead of `--help` per command. It pairs with `jq`:
+
+```bash
+mb __manifest | jq -r '.commands[].command'                                                  # every command name
+mb __manifest | jq -r '.commands[] | select(.command | startswith("transform")) | .command'  # verbs under "transform"
+mb __manifest | jq '.commands[] | select(.command == "card query") | .args'                  # flags + types for a command
+mb __manifest | jq '.commands[] | select(.command == "card list") | .outputSchema'           # output schema before parsing
+```
+
+Use it to (a) enumerate verbs, (b) validate flag names before constructing a command, (c) read an output schema before parsing.
+
+## Resource quirks worth memorizing
+
+Routine verb shapes (list / get / create / update), every flag, and output JSON Schemas live in `mb __manifest` — pull them on demand. Below is only what the manifest does _not_ tell you: the footguns and non-obvious behaviors.
+
+- **db traversal vs. rollup.** Default to granular: `database list` → `database schemas <db-id>` → `database schema-tables <db-id> <schema>` → `table get <table-id> --include fields`. The rollup endpoints (`database get --include tables.fields`, `database metadata <db-id>`) pull megabytes and blow the context window on any real warehouse — use them only on a small/dev db. `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately.
+- **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.
+- **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.
+- **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 (it wraps 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 you get only `{run_id, final:null}`. (→ `transform` skill.)
+- **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only — it 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` (EIDs are a positional used with `--model`; or pass `--body '{"entity_ids":{"card":["…"]}}'`). Useful when an external system hands you an entity id and a verb needs the numeric one.
+- **query / uuid.** `mb query` is the ad-hoc MBQL surface (`--print-schema` → `--dry-run` → run); `mb uuid --count <n>` mints the `lib/uuid` values every MBQL 5 clause needs. Both workflows live in the `mbql` skill.
+
+## 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>`.
+
+- **`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".
+
+If a task spans more than one, load each. Specialized skills assume the conventions above and won't repeat them. `mb skills list` enumerates everything on the installed version.
+
+## 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 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 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.