@metabase/cli 0.2.1 → 0.2.2-alpha.extract-api-client.27e2241

package/dist/{validate-query-D1N30wJ7.mjs → validate-query-DaGYSmpQ.mjs}

@@ -1,6 +1,6 @@
-import { ConfigError, writeJson } from "./capabilities-DOTcPraV.mjs";
-import { assertNotLegacyEnvelopeWrappingMbql5, isMbql5Query, validateQuery } from "./validate-Cqa14t7o.mjs";
-
+import { i as ConfigError } from "./predicates-Bkm2IoeX.mjs";
+import { l as writeJson } from "./cli.mjs";
+import { i as validateQuery, r as isMbql5Query, t as assertNotLegacyEnvelopeWrappingMbql5 } from "./validate-BWchyW0V.mjs";
 //#region src/commands/validate-query.ts
 const skipValidateFlag = { "skip-validate": {
 	type: "boolean",
@@ -31,6 +31,5 @@ function preflightMbql5Query(query, labels, options) {
 	writeJson(outcome);
 	throw new ConfigError(`${labels.contextLabel}: ${outcome.errors.length} error(s) — pass valid MBQL 5 or use the legacy format`);
 }
-
 //#endregion
-export { CARD_DATASET_QUERY_LABELS, MEASURE_DEFINITION_LABELS, SEGMENT_DEFINITION_LABELS, TRANSFORM_SOURCE_QUERY_LABELS, preflightMbql5Query, skipValidateFlag };
+export { preflightMbql5Query as a, TRANSFORM_SOURCE_QUERY_LABELS as i, MEASURE_DEFINITION_LABELS as n, skipValidateFlag as o, SEGMENT_DEFINITION_LABELS as r, CARD_DATASET_QUERY_LABELS as t };

package/dist/{values-DIBAgSyz.mjs → values-Dxf1JEoA.mjs}

@@ -1,9 +1,8 @@
-import { connectionFlags, formatScalar, outputFlags, profileFlag, renderSummary } from "./capabilities-DOTcPraV.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { defineMetabaseCommand } from "./runtime-Ab96yYlM.mjs";
-import { FieldValues, fieldValuesView } from "./field-DsXTeqBy.mjs";
-import { parseId } from "./parse-id-CD54Chc5.mjs";
-
+import { F as outputFlags, I as profileFlag, M as connectionFlags, c as renderSummary, f as formatScalar } from "./cli.mjs";
+import { t as defineMetabaseCommand } from "./runtime-DiKyBxOw.mjs";
+import { t as parseId } from "./parse-id-C_jmKFaa.mjs";
+import { s as FieldValues } from "./field-Cr2DPUG9.mjs";
+import { n as fieldValuesView } from "./field-BPsNa-TO.mjs";
 //#region src/commands/field/values.ts
 var values_default = defineMetabaseCommand({
 	meta: {
@@ -25,19 +24,15 @@ var values_default = defineMetabaseCommand({
 	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 values = await (await getClient()).field.values(id);
 		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");
+			return [`Field ${fieldId} has ${count} cached value${count === 1 ? "" : "s"}${more}:`, ...values.values.map((row) => `  ${formatScalar(row[0])}`)].join("\n");
 		}, ctx);
 	}
 });
-
 //#endregion
-export { values_default as default };
+export { values_default as default };

package/dist/verify-K96rItG5.mjs

@@ -0,0 +1,89 @@
+import { n as createClient } from "./client-BqhzKdLM.mjs";
+import { f as errorMessage, l as TimeoutError, o as MetabaseError, s as NetworkError } from "./predicates-Bkm2IoeX.mjs";
+import { F as tryParseTag, I as SessionProperties, u as USER_AGENT } from "./runtime-DiKyBxOw.mjs";
+import { r as HttpError } from "./network-error-CEb9ymDW.mjs";
+//#region ../client/src/version/probe.ts
+const PROBE_PATH = "/api/session/properties";
+const PROBE_TIMEOUT_MS = 1e4;
+async function probeServer(client, opts = {}) {
+	const properties = await client.requestParsed(SessionProperties, PROBE_PATH, {
+		timeoutMs: PROBE_TIMEOUT_MS,
+		retries: opts.retries ?? 0
+	});
+	return {
+		version: tryParseTag(properties.version.tag),
+		tokenFeatures: properties["token-features"] ?? null
+	};
+}
+//#endregion
+//#region src/core/auth/verify.ts
+const VERIFY_TIMEOUT_MS = 15e3;
+async function verifyAndProbe(url, credential, options = {}) {
+	const { refresh, signal } = options;
+	const mb = createClient({
+		url,
+		credential
+	}, {
+		userAgent: USER_AGENT,
+		...refresh !== void 0 && { refreshCredential: refresh },
+		...signal !== void 0 && { signal }
+	});
+	const userPromise = mb.user.current({
+		timeoutMs: VERIFY_TIMEOUT_MS,
+		retries: 0
+	});
+	const serverPromise = probeServer(mb);
+	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");
+	return {
+		ok: true,
+		user: {
+			id: userResult.value.id,
+			name: userResult.value.common_name,
+			isAdmin: userResult.value.is_superuser
+		},
+		server: serverResult.value
+	};
+}
+function failure(error, which) {
+	if (error instanceof HttpError) return {
+		ok: false,
+		which,
+		kind: error.status === 401 || error.status === 403 ? "auth" : "server",
+		status: error.status,
+		endpoint: error.developerDetail.url,
+		message: error.userMessage
+	};
+	if (error instanceof NetworkError) return {
+		ok: false,
+		which,
+		kind: "network",
+		endpoint: error.developerDetail.url,
+		message: error.userMessage
+	};
+	if (error instanceof TimeoutError) {
+		const detail = error.developerDetail;
+		return {
+			ok: false,
+			which,
+			kind: "network",
+			...detail.kind === "http" && { endpoint: detail.url },
+			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 as t };

package/dist/{wait-CW1OawkI.mjs → wait-DoMDH226.mjs}

@@ -1,10 +1,9 @@
-import { connectionFlags, outputFlags, profileFlag, renderSummary } from "./capabilities-DOTcPraV.mjs";
-import "./command-augment-D9pI9Vbh.mjs";
-import { defineMetabaseCommand } from "./runtime-Ab96yYlM.mjs";
-import { parseId } from "./parse-id-CD54Chc5.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DVF9EnEb.mjs";
-import { SyncTaskOrIdle, formatSyncTask, pollSyncTask, syncTaskIdleView, syncTaskView, throwIfFailedTask } from "./poll-task-CpHGQOd5.mjs";
-
+import { F as outputFlags, I as profileFlag, M as connectionFlags, c as renderSummary } from "./cli.mjs";
+import { t as defineMetabaseCommand } from "./runtime-DiKyBxOw.mjs";
+import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-75SvT7Zv.mjs";
+import { r as parseWaitSchedule } from "./wait-flags-DWEF9tX4.mjs";
+import { c as syncTaskView } from "./git-sync-DxD_ng48.mjs";
+import { a as throwIfFailedTask, i as taskPollOptions, n as formatSyncTask, r as syncTaskIdleView, t as SyncTaskOrIdle } from "./sync-task-BACcrs0i.mjs";
 //#region src/commands/git-sync/wait.ts
 const WaitResult = SyncTaskOrIdle;
 var wait_default = defineMetabaseCommand({
@@ -34,22 +33,15 @@ var wait_default = defineMetabaseCommand({
 	outputSchema: WaitResult,
 	examples: ["mb git-sync wait", "mb git-sync wait --timeout 300000 --json"],
 	async run({ args, ctx, getClient }) {
-		const timeoutMs = parseId(args.timeout, "timeout");
-		const intervalMs = parseId(args.interval, "interval");
-		const client = await getClient();
-		const final = await pollSyncTask(client, {
-			timeoutMs,
-			intervalMs
-		});
+		const schedule = parseWaitSchedule(args);
+		const final = await (await getClient()).gitSync.waitForTask(taskPollOptions(schedule));
 		if (final === null) {
-			const idle = { status: "idle" };
-			renderSummary(idle, syncTaskIdleView, "No git-sync task is running.", ctx);
+			renderSummary({ status: "idle" }, syncTaskIdleView, "No git-sync task is running.", ctx);
 			return;
 		}
 		renderSummary(final, syncTaskView, formatSyncTask(final), ctx);
 		throwIfFailedTask(final, "task");
 	}
 });
-
 //#endregion
-export { wait_default as default };
+export { wait_default as default };

package/dist/{wait-flags-DvNU8ahZ.mjs → wait-flags-DWEF9tX4.mjs}

@@ -1,6 +1,6 @@
-import { parseId } from "./parse-id-CD54Chc5.mjs";
-import { DEFAULT_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from "./poll-DVF9EnEb.mjs";
-
+import { t as interruptSignal } from "./cli.mjs";
+import { t as parseId } from "./parse-id-C_jmKFaa.mjs";
+import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-75SvT7Zv.mjs";
 //#region src/commands/wait-flags.ts
 const waitScheduleFlags = {
 	timeout: {
@@ -30,17 +30,20 @@ const gitSyncWaitFlags = {
 	},
 	...waitScheduleFlags
 };
+function parseWaitSchedule(args) {
+	const interval = args.interval ?? String(2e3);
+	const timeout = args.timeout ?? String(6e5);
+	return {
+		intervalMs: parseId(interval, "interval"),
+		timeoutMs: parseId(timeout, "timeout"),
+		signal: interruptSignal
+	};
+}
 function parseWaitFlags(args) {
-	const interval = args.interval ?? String(DEFAULT_INTERVAL_MS);
-	const timeout = args.timeout ?? String(DEFAULT_TIMEOUT_MS);
 	return {
 		enabled: args.wait === true,
-		schedule: {
-			intervalMs: parseId(interval, "interval"),
-			timeoutMs: parseId(timeout, "timeout")
-		}
+		schedule: parseWaitSchedule(args)
 	};
 }
-
 //#endregion
-export { gitSyncWaitFlags, parseWaitFlags, waitFlags };
+export { waitFlags as i, parseWaitFlags as n, parseWaitSchedule as r, gitSyncWaitFlags as t };

package/dist/window-BkvrP0gB.mjs

@@ -0,0 +1,64 @@
+import { m as projectForList } from "./cli.mjs";
+//#region src/output/window.ts
+const MAX_REQUEST_PAGE_SIZE = 200;
+function windowList(items, range, serverTotal) {
+	const held = items.length;
+	const start = Math.min(range.offset, held);
+	const end = range.limit === void 0 ? held : Math.min(start + range.limit, held);
+	const total = serverTotal ?? held;
+	const beyondWindow = end < held;
+	const withheldByServer = held < total;
+	return buildEnvelope(items.slice(start, end), range, total, beyondWindow || withheldByServer);
+}
+function windowServerPage(data, total, range) {
+	return buildEnvelope(data, range, total, range.offset + data.length < total);
+}
+async function collectForOutput(source, view, opts) {
+	const { range } = opts;
+	const budget = opts.maxBytes <= 0 ? Number.POSITIVE_INFINITY : opts.maxBytes;
+	const fetchMax = range.limit === void 0 ? void 0 : range.limit + 1;
+	const request = {
+		offset: range.offset,
+		...fetchMax !== void 0 && {
+			max: fetchMax,
+			pageSize: Math.min(fetchMax, MAX_REQUEST_PAGE_SIZE)
+		}
+	};
+	const items = [];
+	let total = null;
+	let bytes = 0;
+	let exhausted = true;
+	for await (const page of source(request)) {
+		total = page.total ?? total;
+		for (const item of page.items) {
+			items.push(item);
+			bytes += measure(item, view, opts);
+		}
+		const budgetSpent = bytes > budget;
+		const capReached = fetchMax !== void 0 && items.length >= fetchMax;
+		if (budgetSpent || capReached) {
+			exhausted = false;
+			break;
+		}
+	}
+	const limit = range.limit;
+	return buildEnvelope(limit !== void 0 && items.length > limit ? items.slice(0, limit) : items, range, total, !exhausted);
+}
+function buildEnvelope(data, range, total, moreAvailable) {
+	const returned = data.length;
+	const hasMore = returned > 0 && moreAvailable;
+	return {
+		data,
+		returned,
+		offset: range.offset,
+		...range.limit !== void 0 && { limit: range.limit },
+		total,
+		has_more: hasMore,
+		next_offset: hasMore ? range.offset + returned : null
+	};
+}
+function measure(item, view, opts) {
+	return Buffer.byteLength(JSON.stringify(projectForList(item, view, opts)), "utf8");
+}
+//#endregion
+export { windowList as n, windowServerPage as r, collectForOutput as t };

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@metabase/cli",
-  "version": "0.2.1",
+  "version": "0.2.2-alpha.extract-api-client.27e2241",
   "description": "Metabase CLI",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/metabase/mb-cli.git"
+    "url": "git+https://github.com/metabase/mb-cli.git",
+    "directory": "packages/cli"
   },
   "bin": {
     "mb": "./dist/cli.mjs"
@@ -13,8 +14,7 @@
   "files": [
     "dist",
     "skills",
-    "skill-data",
-    ".claude-plugin"
+    "skill-data"
   ],
   "type": "module",
   "publishConfig": {
@@ -25,23 +25,7 @@
     "build": "tsdown",
     "dev": "tsdown --watch",
     "start": "node dist/cli.mjs",
-    "test": "vitest run --project unit",
-    "test:watch": "vitest --project unit",
-    "test:e2e": "vitest run --project e2e",
-    "test:e2e:watch": "vitest --project e2e",
-    "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",
-    "lint:fix": "oxlint --fix",
-    "lint:skills": "uvx skillsaw lint skill-data/ --strict",
-    "format": "oxfmt",
-    "format:check": "oxfmt --check",
-    "sync:representations": "bun run scripts/sync-representations.ts",
-    "prepublishOnly": "tsdown && publint"
+    "prepublishOnly": "tsdown && publint && ! grep -rE \"(from|import|require)[[:space:]]*\\(?['\\\"]@metabase\" dist/"
   },
   "dependencies": {
     "@clack/prompts": "^0.8.2",
@@ -54,20 +38,6 @@
     "yaml": "^2.8.4",
     "zod": "^4.0.0"
   },
-  "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^22.10.0",
-    "@types/semver": "^7.7.1",
-    "execa": "^9.5.2",
-    "fast-check": "^4.7.0",
-    "js-yaml": "^4.1.0",
-    "oxfmt": "^0.47.0",
-    "oxlint": "^1.62.0",
-    "publint": "^0.3.0",
-    "tsdown": "^0.9.0",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
-  },
   "engines": {
     "node": ">=20.6"
   }

package/skill-data/core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: core
-description: Foundations for driving Metabase from the terminal with the `mb` CLI — authentication and named profiles, the flag/output/`--json` conventions every command shares, JSON body input, command discovery via `--help` (add `--json` for machine-readable schemas), and the per-resource footguns (db, table, field, upload, card, dashboard, collection, segment, measure, timeline, library, setting, search, eid). Load first for any `mb` task; it routes to the specialized skills for deeper work.
+description: Foundations for driving Metabase from the terminal with the `mb` CLI — authentication and named profiles, the flag/output/`--json` conventions every command shares, JSON body input, command discovery via `--help` (add `--json` for machine-readable schemas), and the per-resource footguns (db, table, field, upload, card, dashboard, collection, segment, measure, timeline, alert, subscription, library, setting, search, eid). Load first for any `mb` task; it routes to the specialized skills for deeper work.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -12,8 +12,8 @@ Top-level command groups (run `mb <group> --help` to discover verbs):
 
 ```
 auth | db | table | field | upload | query | card | dashboard | snippet | segment | measure | collection | library
-document | timeline | timeline-event | transform | transform-job | transform-tag | setting | search | git-sync | setup
-eid | uuid | upgrade | skills
+document | timeline | timeline-event | transform | transform-job | transform-tag | alert | subscription | setting
+search | git-sync | setup | eid | uuid | upgrade | skills
 ```
 
 The conventions below — auth, flags, output, body input — hold across **every** group. Per-command flags and examples live in each command's `--help`; add `--json` for the machine-readable form with the output JSON Schema. A few flows have their own skills (see "Specialized skills"). When a card needs a query, prefer MBQL over native SQL (portable, pre-flight-validated — load `mbql`); fall back to native SQL when MBQL can't express it.
@@ -23,7 +23,7 @@ The conventions below — auth, flags, output, body input — hold across **ever
 **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 checks what profiles exist, asks which to use, and passes `--profile <name>` through every command.
 
 ```bash
-mb auth list --json                      # → {data:[{profile,url,authenticated,status,…}], returned, total}
+mb auth list --json                      # → list envelope; data is [{profile,url,authenticated,status,…}]
 mb auth status --json                    # → {profile, present, url} for the default profile
 mb auth status --profile <name> --json   # health probe for one profile
 ```
@@ -60,26 +60,29 @@ Every list/get verb supports the same output flags:
 - `--json` — emit the full JSON envelope, safe for `jq`. Default is human-readable text.
 - `--full` — include every field (the compact projection is the default, and is the agent-facing contract).
 - `--fields a,b.c.d` — project specific dot-paths. Mutually exclusive with `--full`. **Paths are relative to each `data[]` item on list verbs, and to the root on single-item verbs.** So it's `--fields id,name` on `… list` / `database schema-tables` (`data.id` and `data[].id` both fail with `unknown field path: "data.id"`), and `--fields id,name,display` on `card get`, `--fields data.rows` on `mb query` (whose `data` is an object).
-- `--max-bytes <n>` — cap **list** output size (drops trailing items, sets `truncated`). Default 24576 (sized to fit under agent-harness tool-output limits); `0` disables. Single-item commands (`get`) never truncate — when their output exceeds the cap they throw a `ConfigError` (exit 2: "output is N bytes, over the M-byte --max-bytes cap; …") whose tail names the remedy: on schema-shaped commands it is the exact narrower command to run instead — follow it rather than raising the cap.
+- `--max-bytes <n>` — cap output size. Default 24576 (sized to fit under agent-harness tool-output limits); `0` disables. On a list it drops trailing items and sets `truncated` (see below). Single-item commands (`get`) never truncate — over the cap they throw a `ConfigError` (exit 2: "output is N bytes, over the M-byte --max-bytes cap; …") whose tail names the remedy: on schema-shaped commands it is the exact narrower command to run instead — follow it rather than raising the cap.
 - JSON output is a single line when stdout is piped (pretty-printed only at a TTY) — always parse it, never scrape by line position.
 
-List envelope shape (metadata first, so counts and the truncation marker survive if a consumer cuts the tail):
-
-```json
-{
-  "returned": 10,
-  "total": 42,
-  "limit": 50,
-  "truncated": { "reason": "max_bytes", "bytes": 123456 },
-  "data": [
-    /* items */
-  ]
-}
-```
+## List windows and resumption
+
+Every list verb takes `--limit <n>` (items this call returns) and `--offset <n>` (where the window starts, default `0`), and answers with one envelope, metadata first so the counts and the resumption point survive a cut tail: `{returned, offset, limit?, total, has_more, next_offset, truncated?, data}`. `truncated` is `{reason: "max_bytes", bytes: N}`.
+
+- **`has_more` decides whether to keep going — never compare counts.** `total` is the server's count on endpoints that report one and `null` on those that don't, so arithmetic over it is not a termination condition.
+- **To continue, pass `next_offset` back as `--offset`.** When `has_more` is true `next_offset` is past the offset you sent, so the loop advances; when false the walk is over and `next_offset` is `null`.
+- **`truncated` means the byte cap cut the output, not that the data ran out.** `has_more`/`next_offset` are recomputed to the cut point, so a capped list resumes like any window. Its `bytes` is what the untruncated answer would have measured, so it sizes the work left rather than the reply you hold. Narrow rows with `--fields` rather than raising `--max-bytes` — a bigger cap spends context on fields you didn't ask for, and the cap counts only what you asked for, so `--fields` buys rows directly. A capped list always returns at least one row; when not even one fits it exits 2 with "the smallest response this list can produce is N bytes, over the M-byte --max-bytes cap; …".
+- `limit` is echoed only when you passed `--limit` — except `mb search`, which defaults to `--limit 20` (an unbounded search is expensive server-side) and so always reports one. On nouns the server doesn't page, one large `--limit` with narrow `--fields` is a single request; many small `--offset` hops are one request each.
 
-`truncated` is present only when the cap dropped trailing items.
+The whole walk, literally:
 
-`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.
+```bash
+offset=0
+while : ; do
+  out=$(mb table list --db-id 1 --limit 50 --offset "$offset" --fields id,name --profile <n> --json)
+  echo "$out" | jq -c '.data[]'
+  [ "$(echo "$out" | jq -r '.has_more')" = "true" ] || break
+  offset=$(echo "$out" | jq -r '.next_offset')
+done
+```
 
 ## Body input (create / update / run)
 
@@ -87,10 +90,10 @@ Verbs that take a payload accept it from one of four sources, **first non-empty
 
 1. `--body '<inline JSON>'`
 2. `--file <path>` — JSON file
-3. stdin (auto-detected when piped, or explicit `--stdin` where supported)
+3. stdin (auto-detected when piped; `--file -` names it explicitly)
 4. positional argument
 
-Exactly one required; passing two of `--body` / `--file` / `--stdin` is rejected with a `ConfigError`.
+Exactly one required; passing more than one of `--body` / `--file` / a positional argument is rejected with a `ConfigError`.
 
 ```bash
 cat > ./.scratch/body.json <<'EOF'
@@ -122,23 +125,24 @@ mb transform --help --json | jq -r '.commands[].command'  # verbs under "transfo
 
 Routine verb shapes (list / get / create / update), every flag, and output schemas live in each command's `--help` (add `--json` for output schemas). Below is only what help does _not_ tell you: footguns and non-obvious behaviors.
 
-- **db traversal: the hydration ladder.** Start with `database get <db-id> --include tables` — the compact table map (id, name, schema, description per table), one call that fits most databases. Pick the relevant tables, then `table fields <table-id>` per table (bounded: fields are per-table). `--include tables.fields` is the full rollup — small databases only; when either outgrows the cap the error message names the next command down the ladder. Hundreds of tables? Traverse by schema (`database schemas <db-id>` → `database schema-tables <db-id> <schema>`) or look tables up by name (`search <term> --models table --db-id <db-id> --limit 10`). `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
+- **db traversal: the hydration ladder.** Start with `database get <db-id> --include tables` — the compact table map (id, name, schema, description per table), one call that fits most databases. Pick the relevant tables, then `table fields <table-id>` per table (bounded: fields are per-table). `--include tables.fields` is the full rollup — small databases only. Hundreds of tables? Traverse by schema (`database schemas <db-id>` → `database schema-tables <db-id> <schema>`) or look tables up by name (`search <term> --models table --db-id <db-id> --limit 10`). `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
 - **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact; the underlying query_metadata response also carries FK targets and dimensions, visible under `--full`) or use `table fields <id>` (list envelope). `table update` patches table-level metadata only; physical columns aren't editable.
 - **field has no `list`.** Fields are per-table — get them via `table get <id> --include fields`. Never enumerate fields across a whole db (context blow-up). `field summary` is live cardinality `{field_id, count, distincts}`; `field values` is the cached distinct set (`has_more_values: true` ⇒ truncated cache). `field update` patches metadata only (`base_type` isn't editable) — this is where you set a column's `semantic_type` or foreign-key target.
 - **upload (CSV → tables).** `upload csv --file <path>` creates a new table + model (prints `{model_id, table_id}`); `upload append <table-id>` / `upload replace <table-id> --file <path>` add to / overwrite a table **previously created by upload** (columns must match). The destination db+schema is admin-configured, not per-call — check with `mb setting get uploads-settings --json` (`db_id: null` ⇒ uploads off/unconfigured; needs admin to read). `--collection <id|root>` only sets the model's collection. Max 50 MB. Errors: **"The uploads database is not configured."** = no db has uploads enabled; **"Uploads are not enabled."** = the append/replace target isn't an uploaded table.
 - **card.** `dataset_query` is the **flat** `mbql/query` value, not a legacy `{type:"query",query:…}` envelope (→ `mbql`). `--export-format csv|xlsx` streams the raw export (pipe to a file), bypassing the JSON envelope. `archive` is the only delete; unarchive with `update --body '{"archived":false}'`. `visualization_settings` keys are scoped by `display` and aren't pre-flighted — see `visualization`.
 - **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). `create` accepts the **same** `dashcards` array in its initial body — 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` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a card filling only half the width). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix). Layout patterns and per-chart default sizes → the `dashboard` skill; load it before composing any `dashcards` array.
-- **dashboard parameters (filters).** A dashboard's `parameters` array holds its filter widgets; they're part of the dashboard record, so read them with `dashboard get <id> --fields parameters --json` (no separate verb). **Editing replaces the _whole_ array** (like dashcards), so it's a read-modify-write loop: pull the current set with `dashboard get <id> --fields parameters --json`, add/change entries, and send the full array back via `dashboard update --body '{"parameters":[…]}'` (or supply it in `create`). Omitting a parameter deletes it. Each parameter is `{id, type, …}`. **`id` is a descriptive slug-like string you pick (e.g. `order_status`), unique within this dashboard — Metabase stores any non-blank string verbatim. Do NOT invent a random/opaque id by guessing; reuse the `slug`. If you genuinely need an opaque id, mint one with `mb uuid` — never fabricate one.** `type` is a **closed enum**; an unlisted value is a hard parse error that echoes the full allowed set back to you: string ops `string/=` `string/!=` `string/contains` `string/does-not-contain` `string/starts-with` `string/ends-with`; number ops `number/=` `number/!=` `number/between` `number/>=` `number/<=`; date `date/single` `date/range` `date/relative` `date/month-year` `date/quarter-year` `date/all-options`; plus `category`, `id`, `boolean/=`, `temporal-unit`, and bare `number`/`text`/`date`/`boolean`. A parameter only filters a card once it is **mapped**: each dashcard's `parameter_mappings` is `[{parameter_id, target}]` where `parameter_id` must match a parameter's `id` exactly, and `target` is `["dimension", ["field", <field-id>, null]]` for an MBQL card column, `["dimension", ["template-tag", "<tag>"]]` for a native field-filter tag, or `["variable", ["template-tag", "<tag>"]]` for a native raw-value tag. Populate a dropdown with `values_source_type`: `"static-list"` + `values_source_config.values`, or `"card"` + `{card_id, value_field, label_field}`; omit it to pull live distinct values from the mapped field. `dashboard parameter-values <id> <parameter-id> [--query <substr>]` fetches those selectable values (`{values, has_more_values}`); `--query` is a case-insensitive substring search.
+- **dashboard parameters (filters).** A dashboard's `parameters` array holds its filter widgets; they're part of the dashboard record, so read them with `dashboard get <id> --fields parameters --json` (no separate verb). **Editing replaces the _whole_ array** (like dashcards), so it's a read-modify-write loop and omitting a parameter deletes it. A parameter only filters a card once it is **mapped** onto that dashcard's `parameter_mappings` — an unmapped parameter is an inert widget. `type` is a **closed enum**; an unlisted value is a hard parse error that echoes the full allowed set back to you. `dashboard parameter-values <id> <parameter-id> [--query <substr>]` fetches a widget's selectable values (`{values, has_more_values}`; `--query` is a case-insensitive substring search). Parameter types, ids, mapping targets, and value sources → the `dashboard` skill; load it before authoring a `parameters` array.
+- **alert / subscription are two unrelated systems.** `alert` watches one **card** and fires on a send condition (`/api/notification`: a cron string, `channel/email`-prefixed handlers, typed recipients); `subscription` delivers one **dashboard** on a schedule (`/api/pulse`: structured `schedule_type` + hour/day/frame, bare `email` channels, `{id}|{email}` recipients). The bodies are not interchangeable. Both silently deliver nowhere if the server has no SMTP / Slack app — check `mb setting get 'email-configured?'` (quote it; the `?` is a shell glob) before creating either. Their list-valued fields (`handlers`/`subscriptions`, `channels`/`cards`) **replace wholesale** on update, so adding one recipient is a read-modify-write. `mb card alerts <id>` and `mb dashboard subscriptions <id>` list what's already attached to a card/dashboard; `archive` deactivates rather than deletes. Load the `notification` skill before authoring either body.
 - **snippet `--archived` is a swap, not a union** — list returns _either_ active _or_ archived rows, never both. (Same for `--filter archived` on dashboard/collection.)
 - **segment / measure.** `update` and `archive` require a non-blank `revision_message` (audit-logged); the CLI does not synthesize it on `update`. `archive` defaults to `"Archived via mb CLI"` — override with `--revision-message`. `definition` is a flat MBQL clause (→ `mbql`): segment = a filter, measure = exactly one aggregation.
 - **timeline / timeline-event.** Timelines are collection-scoped event annotations for time-series charts: a timeline's events render only on time-series questions saved in the **same collection** (`collection_id`; null = root) — sub-collections do **not** inherit, and events never draw on dashboard cards, only in the question (and collection) view. To annotate a question's chart, create the timeline in that question's collection, then add events; an event only draws when its `timestamp` falls inside the chart's displayed time range. Event `create` requires `timestamp` (ISO 8601), `timezone` (IANA name), `time_matters` (true = the time of day is significant, false = date-only), and `timeline_id` — the API never auto-creates a default timeline (that's UI-only). There is no `timeline-event list`; enumerate with `timeline events <id>` (`--archived` to include archived). Archiving a timeline cascades `archived` to its events; `delete` is a **hard** delete of the timeline and all its events — prefer `archive`.
-- **collection `<ref>`** accepts four forms only — positive int, `root`, `trash`, or a 21-char entity_id; anything else is a client-side `ConfigError`. `collection items` auto-paginates (cap with `--limit`, which then omits `total`). `collection tree` is **JSON-only** (`--format text` is rejected). A transform collection needs `collection create --namespace transforms`.
+- **collection `<ref>`** accepts four forms only — positive int, `root`, `trash`, or a 21-char entity_id; anything else is a client-side `ConfigError`. `collection items` pages the server endpoint, pulling only as far as the output cap can show — read `has_more`/`next_offset` to continue. `collection tree` is **JSON-only** (`--format text` is rejected). A transform collection needs `collection create --namespace transforms`.
 - **setting set** parses the value as **strict JSON**: a string is `'"value"'` (inner quotes), booleans `true`/`false`, numbers bare. Wrong quoting silently errors — confirm with `setting get <key>` after. `setting get --json` works on every value type (wrapping bare-text responses into `{key, value}`).
 - **search vs. list.** For plain enumeration of cards/dashboards/collections use the dedicated `… list` verbs; reach for `search --models <kind>` only for ranking against a query string or a cross-resource lookup.
 - **transform.** Iterate with `transform update <id>`, never `delete` + `create` (keeps the row, `entity_id`, materialized table, and YAML filename — avoids `_2` suffixes and noisy git history). `transform run` needs `--wait` (or `--sync`, which also waits for the output table to register and returns `target_table_id`) or you get only `{run_id, final:null}`. (→ `transform`.)
 - **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only — errors against an already-configured one. Mostly for bootstrapping local / e2e instances.
 - **eid** translates a string entity id → numeric id: `mb eid --model <model> <eid1,eid2> --json`. Entity ids are NanoIDs that can start with `-`, which the positional form misreads as a flag (shell quotes don't help) — for those, use `--body '{"entity_ids":{"card":["-…"]}}'` (the id is a JSON string value, immune to flag parsing).
-- **library.** EE-only (`library` premium feature, v59+). The Library is a curated subtree (`library-data` "Data" + `library-metrics` "Metrics" under a `library` root): tables published to **Data** appear first in data pickers and rank up in search; metrics saved to **Metrics** are prioritized in nav, search, and the query builder — it's how you tell people (and agents) "start from these, they're trusted." `library get` shows the Library and its Data/Metrics collection ids; `library create` provisions it (idempotent). `library publish --table-ids/--db-ids/--schemas` publishes tables into Data — it **resolves the Data collection itself and creates the Library if absent** (no collection id to find); each `--schemas` entry is `<db-id>:<schema>` (e.g. `1:public`), not a bare name. `publish` cascades to upstream FK dependencies, `unpublish` to downstream dependents; both need **admin or data-analyst** (Curate alone won't publish) and exit **403** without write **and** query permission on every affected table. Publish status shows on the table: `table get`/`table list` carry `is_published` (`collection_id` under `--full`). Good candidates are finished, analysis-ready tables — clean/combine via transforms first, then publish the polished result.
+- **library.** EE-only (`library` premium feature, v59+). The Library is a curated subtree (`library-data` "Data" + `library-metrics` "Metrics" under a `library` root): tables published to **Data** appear first in data pickers and rank up in search; metrics saved to **Metrics** are prioritized in nav, search, and the query builder — it's how you tell people (and agents) "start from these, they're trusted." `library get` shows the Library and its Data/Metrics collection ids; `library create` provisions it (idempotent). `library publish --table-ids/--db-ids/--schemas` publishes tables into Data — it **resolves the Data collection itself and creates the Library if absent** (no collection id to find); each `--schemas` entry is `<db-id>:<schema>` (e.g. `1:public`), not a bare name. `publish` cascades to upstream FK dependencies, `unpublish` to downstream dependents; both need **admin or data-analyst** (Curate alone won't publish) and exit **403** without write **and** query permission on every affected table. Publish status shows on the table: `table get`/`table list` carry `is_published` (`collection_id` under `--full`). Good candidates are finished, analysis-ready tables — clean/combine via transforms first, then publish the polished result. Publishing does not put the Data collection in the git-sync scope: on a remote-sync instance, `mb git-sync add-collection <data-collection-id>` is what makes exports carry the published tables' metadata (see the `git-sync` skill).
 - **query / uuid.** `mb query` is the ad-hoc MBQL surface (`--print-schema` → `--dry-run` → run); `mb uuid --count <n>` mints the `lib/uuid` values MBQL clauses need. Both live in `mbql`.
 
 ## Specialized skills (load on demand)
@@ -150,6 +154,7 @@ This file is enough for any single-command task. For anything deeper, load the r
 - **`visualization`** — choosing a card's `display` and authoring `visualization_settings`. The presentation counterpart to `mbql`.
 - **`dashboard`** — building interactive dashboards: wiring filters (parameters + mappings), linked/cascading filters, cross-filtering, click behavior, series, and tabs. Load beyond a plain card-layout task.
 - **`metadata`** — setting field/table metadata: semantic types, foreign-key targets, dropdown/scan behavior, and column visibility, and the downstream features each unlocks. Load when editing what a column _means_, not its data.
+- **`notification`** — scheduled delivery: question alerts (`mb alert`) and dashboard subscriptions (`mb subscription`). Choosing between them, the two schedule/recipient contracts, channel prerequisites, testing a send.
 - **`transform`** — transform body JSON, create + run-with-wait, run inspection, tags, jobs.
 - **`document`** — Metabase documents (TipTap body, embedding cards).
 - **`git-sync`** — round-tripping content to/from a git remote.

package/skill-data/dashboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dashboard
-description: Build Metabase dashboards via the `mb` CLI — lay out dashcards on the 24-column grid (`{col,row,size_x,size_y}` math, per-chart default sizes) and turn cards into a filterable, cross-linked app. Covers wiring filters to cards (parameters + parameter_mappings), the field-filter vs. raw-variable target grammar, linked/cascading filters and their foreign-key requirement, cross-filtering, click-through, multi-series overlays, and tabs. The parameter type enum and whole-array replace semantics live in `core`. Triggers — "build a dashboard from these cards", "my dashboard is squished into half the width", "wire a filter to these cards", "make a filter cascade", "click a bar to filter the other charts", "add a dashboard tab", "add a second series", "why isn't my filter showing".
+description: Build Metabase dashboards via the `mb` CLI — lay out dashcards on the 24-column grid (`{col,row,size_x,size_y}` math, per-chart default sizes) and turn cards into a filterable, cross-linked app. Covers wiring filters to cards (parameters + parameter_mappings), the field-filter vs. raw-variable target grammar, linked/cascading filters and their foreign-key requirement, cross-filtering, click-through, multi-series overlays, and tabs. The whole-array replace semantics live in `core`. Triggers — "build a dashboard from these cards", "my dashboard is squished into half the width", "wire a filter to these cards", "make a filter cascade", "click a bar to filter the other charts", "add a dashboard tab", "add a second series", "why isn't my filter showing".
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 ---
 
@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 A dashboard starts as cards on a grid; it becomes an **app** when filters drive the cards, charts cross-filter each other, and clicks navigate. This skill owns both: the grid layout and the interactive layer.
 
-**`core` owns the transport mechanics** — the whole-array replace semantics (editing `dashcards` or `parameters` replaces the entire set; omitted entries are deleted; new cards use negative ids), `update-dashcard` for a single safe patch vs. `update --body` for a full replace, the closed `parameter.type` enum, and the `parameter-values` verb. Read it first (`mb skills get core`). **`visualization`** owns each card's chart and the full `click_behavior` key catalog.
+**`core` owns the transport mechanics** — the whole-array replace semantics (editing `dashcards` or `parameters` replaces the entire set; omitted entries are deleted; new cards use negative ids), `update-dashcard` for a single safe patch vs. `update --body` for a full replace, and the `parameter-values` verb. Read it first (`mb skills get core`). **`visualization`** owns each card's chart and the full `click_behavior` key catalog.
 
 Inspect before you wire: `mb dashboard get <id> --json` hydrates `parameters`, `dashcards`, and `tabs`; `mb dashboard cards <id>` lists just the dashcards.
 
@@ -47,6 +47,10 @@ A dashboard filter is one entry in the dashboard's `parameters` array **plus** a
   "target": ["dimension", ["field", 1779, null]] }
 ```
 
+**`id` is a slug-like string you pick** (e.g. `order_status`), unique within the dashboard — Metabase stores any non-blank string verbatim, so reuse the `slug` rather than guessing an opaque value. If you genuinely need an opaque id, mint one with `mb uuid`; never fabricate one.
+
+**`type` is a closed enum** — an unlisted value is a hard parse error that echoes the allowed set back: string ops `string/=` `string/!=` `string/contains` `string/does-not-contain` `string/starts-with` `string/ends-with`; number ops `number/=` `number/!=` `number/between` `number/>=` `number/<=`; date `date/single` `date/range` `date/relative` `date/month-year` `date/quarter-year` `date/all-options`; location `location/city` `location/state` `location/zip_code` `location/country`; plus `category`, `id`, `boolean/=`, `temporal-unit`, and bare `number`/`text`/`date`/`boolean`.
+
 The `target` grammar depends on what the card is:
 
 | Card's query                | `target`                                     |

package/skill-data/document/SKILL.md

@@ -20,13 +20,13 @@ mb document update <id> --file patch.json --profile <name> --json   # PATCH sema
 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}` and omits the (potentially huge) `document` body — pull the body with `get --full`.
+- `list` returns the standard list envelope (see `core`). The compact item is `{id, name, collection_id, archived, creator_id, can_write}` and omits 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`, and `cards` (inline card creation works on update too, not just create — see below). 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** — the CLI validates before sending and rejects a body missing any (`every … node needs a non-empty string _id (mint with mb uuid)`). Other node types (`doc`, `text`, `listItem`, `resizeNode`, `flexContainer`, …) take no `_id` and are left alone. Without them the editor backfills ids when the document opens, which makes a freshly-saved document show a spurious "unsaved changes" prompt.
+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** — the CLI validates before sending and rejects a body missing any (`every … node needs a non-empty string _id`). Other node types (`doc`, `text`, `listItem`, `resizeNode`, `flexContainer`, …) take no `_id` and are left alone. Without them the editor backfills ids when the document opens, which makes a freshly-saved document show a spurious "unsaved changes" prompt.
 
 Mint the ids with `mb uuid --count <n> --json` (→ `["…", …]`), one per id-bearing node, and set each as that node's `attrs._id`.