@metabase/cli 0.1.8 → 0.1.10

package/dist/{update-UaPqSfPN.mjs → update-Dri4Zg2H.mjs}

@@ -1,15 +1,14 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-CTVL5CdB.mjs";
-import { defineMetabaseCommand } from "./runtime-B40L_bj8.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import { renderSummary } from "./render-0_GsapXa.mjs";
-import "./input-cMSEqISy.mjs";
-import { parseId } from "./parse-id-D1LTTt9L.mjs";
-import { readBody } from "./body-DDYKoyMt.mjs";
-import { bodyInputFlags } from "./body-flags-D7q87Btw.mjs";
-import "./validate-dPEOnOf8.mjs";
-import { MEASURE_DEFINITION_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-CYvOP8Ld.mjs";
-import { Measure, MeasureUpdateInput, measureView } from "./measure-Bt3InQsA.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BWXBhqLW.mjs";
+import { defineMetabaseCommand } from "./runtime-colqvhLf.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
+import "./input-xewHccej.mjs";
+import { parseId } from "./parse-id--iVTCKSo.mjs";
+import { readBody } from "./body-BdRyuvU4.mjs";
+import { bodyInputFlags } from "./body-flags-D78h_-Ua.mjs";
+import "./validate-B62TRDGV.mjs";
+import { MEASURE_DEFINITION_LABELS, preflightMbql5Query, skipValidateFlag } from "./validate-query-BpiN1CFu.mjs";
+import { Measure, MeasureUpdateInput, measureView } from "./measure-COGAoZpo.mjs";
 
 //#region src/commands/measure/update.ts
 var update_default = defineMetabaseCommand({

package/dist/{update-dashcard-DK9X91ha.mjs → update-dashcard-D_-ura3Y.mjs}

@@ -1,13 +1,12 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-CTVL5CdB.mjs";
-import { defineMetabaseCommand } from "./runtime-B40L_bj8.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import { renderSummary } from "./render-0_GsapXa.mjs";
-import "./input-cMSEqISy.mjs";
-import { parseId } from "./parse-id-D1LTTt9L.mjs";
-import { readBody } from "./body-DDYKoyMt.mjs";
-import { bodyInputFlags } from "./body-flags-D7q87Btw.mjs";
-import { DashboardDetail, Dashcard, DashcardPatchInput, dashcardView } from "./dashboard-B4bn3z6t.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BWXBhqLW.mjs";
+import { defineMetabaseCommand } from "./runtime-colqvhLf.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
+import "./input-xewHccej.mjs";
+import { parseId } from "./parse-id--iVTCKSo.mjs";
+import { readBody } from "./body-BdRyuvU4.mjs";
+import { bodyInputFlags } from "./body-flags-D78h_-Ua.mjs";
+import { DashboardDetail, Dashcard, DashcardPatchInput, dashcardView } from "./dashboard-FY5UzJ_Z.mjs";
 
 //#region src/commands/dashboard/update-dashcard.ts
 var update_dashcard_default = defineMetabaseCommand({

package/dist/{upgrade-UqdvTikR.mjs → upgrade-CFkZ4USY.mjs}

@@ -1,13 +1,12 @@
-import { AbortError, NetworkError, TimeoutError, UnknownError, errorMessage } from "./command-augment-BH9qgQ5u.mjs";
-import { outputFlags, package_default } from "./error-CTVL5CdB.mjs";
-import { HttpError, USER_AGENT, combineAborts, defineMetabaseCommand, parseJson, throwIfAborted } from "./runtime-B40L_bj8.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import { renderItem, writeText } from "./render-0_GsapXa.mjs";
-import { promptConfirm } from "./prompt-CFKoys7k.mjs";
-import { streamProcess } from "./process-CM7Uu5q_.mjs";
+import { AbortError, NetworkError, TimeoutError, UnknownError, errorMessage, isNotFoundError } from "./command-augment-BH9qgQ5u.mjs";
+import { outputFlags, package_default } from "./error-BWXBhqLW.mjs";
+import { HttpError, USER_AGENT, combineAborts, defineMetabaseCommand, parseJson, throwIfAborted } from "./runtime-colqvhLf.mjs";
+import { renderItem, writeText } from "./capabilities-7L9GVMd_.mjs";
+import { promptConfirm } from "./prompt-u4WhE4T5.mjs";
 import { z } from "zod";
 import { realpathSync } from "node:fs";
 import { compare, valid } from "semver";
+import { spawn } from "node:child_process";
 
 //#region src/core/http/npm-registry.ts
 const DEFAULT_REGISTRY = "https://registry.npmjs.org";
@@ -250,6 +249,34 @@ function compareSemver(a, b) {
 	return compare(a, b);
 }
 
+//#endregion
+//#region src/runtime/process.ts
+var ProcessNotFoundError = class extends Error {
+	command;
+	constructor(command) {
+		super(`command not found: ${command}`);
+		this.name = "ProcessNotFoundError";
+		this.command = command;
+	}
+};
+const stdoutDecoder = new TextDecoder("utf-8");
+function streamProcess(command, args, options = {}) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			stdio: "inherit",
+			...options.shell === true ? { shell: true } : {}
+		});
+		child.on("error", (error) => {
+			if (isNotFoundError(error)) {
+				reject(new ProcessNotFoundError(command));
+				return;
+			}
+			reject(error);
+		});
+		child.on("close", (code) => resolve(code));
+	});
+}
+
 //#endregion
 //#region src/commands/upgrade.ts
 const UpgradeCommandSchema = z.object({

package/dist/{uuid-BWCaWG4O.mjs → uuid-DpinhSxA.mjs}

@@ -1,8 +1,7 @@
 import { ConfigError } from "./command-augment-BH9qgQ5u.mjs";
-import { outputFlags } from "./error-CTVL5CdB.mjs";
-import { defineMetabaseCommand, parseInteger } from "./runtime-B40L_bj8.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import { writeJson, writeText } from "./render-0_GsapXa.mjs";
+import { outputFlags } from "./error-BWXBhqLW.mjs";
+import { defineMetabaseCommand, parseInteger } from "./runtime-colqvhLf.mjs";
+import { writeJson, writeText } from "./capabilities-7L9GVMd_.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 

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

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

package/dist/{validate-query-CYvOP8Ld.mjs → validate-query-BpiN1CFu.mjs}

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

package/dist/{values-D_wycrcr.mjs → values-BSS4DRxk.mjs}

@@ -1,10 +1,9 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-CTVL5CdB.mjs";
-import { defineMetabaseCommand } from "./runtime-B40L_bj8.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import { formatScalar, renderSummary } from "./render-0_GsapXa.mjs";
-import { FieldValues, fieldValuesView } from "./field-E0IBy4Uw.mjs";
-import { parseId } from "./parse-id-D1LTTt9L.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BWXBhqLW.mjs";
+import { defineMetabaseCommand } from "./runtime-colqvhLf.mjs";
+import { formatScalar, renderSummary } from "./capabilities-7L9GVMd_.mjs";
+import { FieldValues, fieldValuesView } from "./field-MGxpNQUH.mjs";
+import { parseId } from "./parse-id--iVTCKSo.mjs";
 
 //#region src/commands/field/values.ts
 var values_default = defineMetabaseCommand({

package/dist/{verify-D7hb6VMy.mjs → verify-B_A7v8TY.mjs}

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

package/dist/{wait-B5IpNFCG.mjs → wait-D3iSnjMM.mjs}

@@ -1,11 +1,10 @@
 import "./command-augment-BH9qgQ5u.mjs";
-import { connectionFlags, outputFlags, profileFlag } from "./error-CTVL5CdB.mjs";
-import { defineMetabaseCommand } from "./runtime-B40L_bj8.mjs";
-import "./capabilities-7e9MgquN.mjs";
-import { renderSummary } from "./render-0_GsapXa.mjs";
-import { parseId } from "./parse-id-D1LTTt9L.mjs";
-import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-D8mG49IN.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DxpnK1wW.mjs";
+import { connectionFlags, outputFlags, profileFlag } from "./error-BWXBhqLW.mjs";
+import { defineMetabaseCommand } from "./runtime-colqvhLf.mjs";
+import { renderSummary } from "./capabilities-7L9GVMd_.mjs";
+import { parseId } from "./parse-id--iVTCKSo.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-BucRFJT-.mjs";
+import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-DTzKB3T3.mjs";
 
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;

package/dist/{wait-flags-CNIeSq0_.mjs → wait-flags-_LnHOeBA.mjs}

@@ -1,5 +1,5 @@
-import { parseId } from "./parse-id-D1LTTt9L.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DxpnK1wW.mjs";
+import { parseId } from "./parse-id--iVTCKSo.mjs";
+import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-BucRFJT-.mjs";
 
 //#region src/commands/wait-flags.ts
 const waitScheduleFlags = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metabase/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Metabase CLI",
   "license": "AGPL-3.0",
   "repository": {

package/skill-data/core/SKILL.md

@@ -1,28 +1,26 @@
 ---
 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, documents, 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
+document | 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.
+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. When a **question** (card) needs a query, prefer MBQL over native SQL — it's portable across warehouse engines and the CLI pre-flight-validates it. Try it first, but don't force it: fall back to native SQL when MBQL can't express the query, or when an MBQL body keeps failing server-side and you can't resolve it.
 
 ## 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
@@ -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:
@@ -140,28 +128,27 @@ Use it to (a) enumerate verbs, (b) validate flag names before constructing a com
 
 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.
+- **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; `sync-schema --wait` blocks until `initial_sync_status: complete`.
 - **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. **Dashcard geometry: the grid is 24 columns wide.** Each dashcard's `{col, row, size_x, size_y}` is in grid units — `col` (0-indexed, left edge) and `size_x` are columns, `row`/`size_y` are rows; **full-width is `size_x: 24`** (`size_x: 12` is half a row — the usual cause of a card that only fills half the width, since it's a common per-chart default). Keep `col + size_x ≤ 24`, start each card's `col` at 0 for a full-width stack, and don't overlap cards (the server stores whatever you send — it won't auto-fix collisions).
 - **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.)
+- **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 run's output table to register and returns `target_table_id`) 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.
+- **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":["…"]}}'`). Entity ids are NanoIDs that can start with `-`, which the positional form misreads as a flag (shell quotes don't help — the `-` survives into argv). For an id that may start with `-`, use `--body` — the id is a JSON string value, immune to flag parsing: `mb eid --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>`.
+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/document/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: document
+description: Author and edit Metabase documents via `mb` — the TipTap (ProseMirror) JSON body shape, the node-type inventory (paragraphs, headings, lists, plus the Metabase-custom `cardEmbed` / `smartLink` / `flexContainer` / `resizeNode`), the per-node-type `_id` requirement, embedding existing or brand-new cards, and the list/get/create/update/archive verbs. Load when the user touches documents — "create a document", "add a card to a document", "edit a document", "list documents", or anything `mb document …`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Documents
+
+A **document** is a Metabase rich-text page (a "report" / notebook) that mixes prose with embedded saved questions and links to other Metabase entities. The body is a **TipTap** JSON tree (TipTap is the editor; the wire format is ProseMirror JSON, and the server stores it under `content_type: "application/json+vnd.prose-mirror"`).
+
+This skill covers authoring the body and driving the verbs. General flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`).
+
+## Command surface
+
+```bash
+mb document list --profile <name> --json                 # non-archived docs visible to you
+mb document get <id> --profile <name> --full --json      # one doc incl. its TipTap body
+mb document create --file doc.json --profile <name> --json
+mb document update <id> --file patch.json --profile <name> --json   # PATCH semantics
+mb document archive <id> --profile <name> --json         # soft-delete (PUT archived:true)
+```
+
+- `list` returns the standard envelope (`{data, returned, total}`). The compact item is `{id, name, collection_id, archived, creator_id, can_write}` — it does **not** include the (potentially huge) `document` body. Pull the body with `get --full`.
+- `archive` is the only delete, mirroring `card` / `dashboard`. **Unarchive** with `mb document update <id> --body '{"archived":false}'`.
+- `update` is PATCH — send only the keys you want to change (`name`, `document`, `collection_id`, `collection_position`, `archived`). Replacing `document` replaces the **whole** body; there is no partial-node patch.
+
+## Node ids (`_id`)
+
+The editor anchors only these node types with an `_id` (a UUID): `paragraph`, `heading`, `codeBlock`, `orderedList`, `bulletList`, `blockquote`, `cardEmbed`, `supportingText`. **`create`/`update` require a non-empty `_id` on every node of those types** and reject a body missing any; other node types (`doc`, `text`, `listItem`, `resizeNode`, `flexContainer`, …) don't take an `_id` and are left alone. Mint the ids with the bundled `uuid` command — one per id-bearing node:
+
+```bash
+mb uuid --count 5 --json     # → ["…", …]   one UUID per id-bearing node
+```
+
+Set each as that node's `attrs._id`. Without them the editor backfills ids when the document opens, which makes a freshly-saved document show a spurious "unsaved changes" prompt.
+
+## Body shape (create / update)
+
+The create body is `{name, document, collection_id?, collection_position?}`. `name` and `document` are required on create; everything is optional on update.
+
+`document` is the TipTap tree — a root `doc` node whose `content` is an array of block nodes (replace each `<uuid-N>` with an `mb uuid` value):
+
+```json
+{
+  "name": "Weekly report",
+  "collection_id": 12,
+  "document": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "heading",
+        "attrs": { "level": 1, "_id": "<uuid-1>" },
+        "content": [{ "type": "text", "text": "Weekly report" }]
+      },
+      {
+        "type": "paragraph",
+        "attrs": { "_id": "<uuid-2>" },
+        "content": [{ "type": "text", "text": "Orders trended up this week." }]
+      }
+    ]
+  }
+}
+```
+
+`collection_id: null` (or omitted) files the document in "Our analytics" (the root). `collection_id` accepts any normal analytics collection id (unlike transforms, documents are not namespace-restricted).
+
+## Node inventory
+
+Every node is `{ "type": string, "attrs"?: object, "content"?: [nodes], "text"?: string, "marks"?: [marks] }`. The id-bearing types listed above carry `attrs._id`; the rest don't.
+
+**Standard text nodes** (TipTap StarterKit):
+
+- `doc` — the root; `content` holds block nodes.
+- `paragraph` — `content` is inline nodes (usually `text`). An empty paragraph (`{ "type": "paragraph", "attrs": { "_id": "<uuid>" } }`) is a blank line.
+- `text` — a leaf with `text` and optional `marks` (no `_id`).
+- `heading` — `attrs.level` 1–6.
+- `bulletList` / `orderedList` — `content` is `listItem` nodes (no `_id`); each `listItem` wraps `paragraph`(s).
+- `blockquote`, `codeBlock`, `horizontalRule`, `hardBreak`, `image`.
+
+**Marks** on `text` (the `marks` array): `bold`, `italic`, `strike`, `code`, plus `link` (`attrs.href`). Example: `{ "type": "text", "text": "important", "marks": [{ "type": "bold" }] }`.
+
+**Metabase-custom nodes** (the reason a document is more than a wiki page):
+
+- **`cardEmbed`** — an embedded saved question. Block, atomic, id-bearing. `attrs: { "id": <card-id>, "name": <string|null>, "_id": "<uuid>" }`. `name` overrides the displayed title (`null` = use the card's own name). Card embeds are commonly wrapped in a `resizeNode` to give them a fixed height.
+- **`resizeNode`** — wraps a single `cardEmbed` or `flexContainer` to make it resizable (no `_id`). `attrs: { "height": <px>, "minHeight": <px> }`, `content` is exactly one `cardEmbed`/`flexContainer`.
+- **`flexContainer`** — a horizontal row of 1–3 `cardEmbed` / `supportingText` cells side by side (no `_id`). `attrs.columnWidths` is an array of width percentages.
+- **`supportingText`** — a text column that sits next to a card inside a `flexContainer` (id-bearing); `content` is the usual block nodes (`paragraph`, `heading`, lists, …).
+- **`smartLink`** — an inline reference to a Metabase entity (renders as a live chip). Inline, atomic, no `_id`. `attrs: { "entityId": <id>, "model": <model>, "label": <string|null>, "href": <relative-path> }`. `model` ∈ `card`, `dataset`, `metric`, `dashboard`, `collection`, `table`, `database`, `document`, `transform`, `segment`, `measure`, `user`, `action`, `indexed-entity`.
+- **`metabot`** — an inline Metabot prompt block.
+
+## Embedding an existing card
+
+A document embedding an existing card (id 114) under a heading (only the id-bearing nodes carry `_id`):
+
+```json
+{
+  "type": "doc",
+  "content": [
+    {
+      "type": "heading",
+      "attrs": { "level": 2, "_id": "<uuid-1>" },
+      "content": [{ "type": "text", "text": "Orders" }]
+    },
+    {
+      "type": "resizeNode",
+      "attrs": { "height": 400, "minHeight": 200 },
+      "content": [{ "type": "cardEmbed", "attrs": { "id": 114, "name": null, "_id": "<uuid-2>" } }]
+    },
+    { "type": "paragraph", "attrs": { "_id": "<uuid-3>" } }
+  ]
+}
+```
+
+To embed an existing card, find its id with `mb card list --profile <name> --json` (or `mb search --models card "<text>"`), then reference it in a `cardEmbed`.
+
+## Creating brand-new cards inline with the document
+
+You can create cards atomically with the document instead of pre-creating them. Reference each new card by a **negative** id in its `cardEmbed.attrs.id`, then supply the card definitions in a top-level `cards` map keyed by the same negative ids. The server creates the real cards and rewrites the negative ids to the real positive ids in the stored body.
+
+```json
+{
+  "name": "Auto report",
+  "document": {
+    "type": "doc",
+    "content": [
+      { "type": "cardEmbed", "attrs": { "id": -1, "name": null, "_id": "<uuid-1>" } },
+      { "type": "paragraph", "attrs": { "_id": "<uuid-2>" } }
+    ]
+  },
+  "cards": {
+    "-1": {
+      "name": "Order count",
+      "display": "scalar",
+      "dataset_query": { "...": "an MBQL or native query — see the mbql skill" },
+      "visualization_settings": {}
+    }
+  }
+}
+```
+
+Each entry in `cards` needs at least `{name, dataset_query, display, visualization_settings}` (these are card definitions, not TipTap nodes, so they take no `_id`). Author the `dataset_query` with the `mbql` skill (`mb skills get mbql`) and the `visualization_settings` with the `viz` skill. For most edits, prefer embedding cards that already exist (a plain positive `id` in `cardEmbed`) — inline creation is for "build the report and its questions in one shot".
+
+## Iterating on a document
+
+`update` replaces the whole `document` body, so the safe loop is **read → edit → write**. A fetched body already carries `_id`s on its id-bearing nodes, so preserve them — only mint new ones for id-bearing nodes you add:
+
+```bash
+mb document get <id> --full --profile <name> --json | jq '.document' > /tmp/body.json
+# edit /tmp/body.json (add nodes — give each new id-bearing node a fresh `mb uuid` _id) …
+jq -n --slurpfile d /tmp/body.json '{document: $d[0]}' > /tmp/patch.json
+mb document update <id> --file /tmp/patch.json --profile <name> --json
+```
+
+Don't hand-merge a partial node tree into a live document — pull the current `document`, mutate the array, and PUT the whole thing back. To rename without touching the body, patch only `name`: `mb document update <id> --body '{"name":"New title"}'`.
+
+## Don't
+
+- Don't omit `_id` on an id-bearing node (`paragraph`, `heading`, `codeBlock`, `orderedList`, `bulletList`, `blockquote`, `cardEmbed`, `supportingText`) — `create`/`update` reject the body ("did not match expected schema"). Mint ids with `mb uuid`.
+- Don't paste a whole `document get` response into `update` — `update` only accepts `name`, `document`, `collection_id`, `collection_position`, `archived`. Send the body under the `document` key, not the full record.
+- Don't put the full `document` body in `list` expectations — `list` is compact and omits it by design; use `get --full`.
+- Don't invent node types. Stick to the inventory above; unknown block types render as empty/broken in the editor even though the response schema is lenient.
+- Don't author a card's `dataset_query` or `visualization_settings` from this skill alone — load `mbql` and `viz`.