@metabase/cli 0.3.1-alpha.support-worktrees.b634907 → 0.3.1-alpha.versioning.9ac5f50

package/dist/upload-DzGTlldn.mjs

@@ -0,0 +1,13 @@
+import { t as defineCommandGroup } from "./group-CmVCLBDz.mjs";
+//#region src/commands/upload/index.ts
+var upload_default = defineCommandGroup({
+	name: "upload",
+	description: "Upload CSV files into Metabase",
+	subCommands: {
+		csv: () => import("./csv-CUQvcCEk.mjs").then((m) => m.default),
+		append: () => import("./append-B9Htvmab.mjs").then((m) => m.default),
+		replace: () => import("./replace-BmAqD3zY.mjs").then((m) => m.default)
+	}
+});
+//#endregion
+export { upload_default as default };

package/dist/{upload-BPd1Uzxc.mjs → upload-akKFxpVA.mjs}

@@ -1,7 +1,7 @@
-import { H as profileFlag, R as connectionFlags, V as outputFlags, p as renderSummary } from "./cli.mjs";
-import { t as defineMetabaseCommand } from "./runtime-CNAZ_FuR.mjs";
+import { I as outputFlags, L as profileFlag, N as connectionFlags, c as renderSummary } from "./cli.mjs";
+import { t as defineMetabaseCommand } from "./runtime-BQiGgbgZ.mjs";
 import { t as ContentTranslationUploadResult } from "./content-translation-BrHOrmj9.mjs";
-import { n as requireUploadFilePath, t as readCsvFile } from "./upload-CD555ui1.mjs";
+import { n as requireUploadFilePath, t as readCsvFile } from "./upload-BUd3MG90.mjs";
 //#region src/output/views/content-translation.ts
 const contentTranslationUploadView = {
 	compactPick: ContentTranslationUploadResult,
@@ -18,11 +18,7 @@ var upload_default = defineMetabaseCommand({
 		description: "Replace the complete content translation dictionary from CSV"
 	},
 	details: "Uploads one complete dictionary and replaces every active content translation on the server. Keep the canonical full CSV in version control and download the current dictionary before replacing it. Metabase accepts dictionaries up to 1.5 MiB.",
-	capabilities: {
-		minVersion: 58,
-		tokenFeature: "content_translation"
-	},
-	worktree: "main-only",
+	requires: ["contentTranslation.upload"],
 	args: {
 		...outputFlags,
 		...profileFlag,

package/dist/{uuid-CFN8LIkP.mjs → uuid-oVdJ62eA.mjs}

@@ -1,6 +1,5 @@
-import { i as ConfigError } from "./predicates-Bkm2IoeX.mjs";
-import { V as outputFlags, h as writeText, m as writeJson } from "./cli.mjs";
-import { K as parseInteger, t as defineMetabaseCommand } from "./runtime-CNAZ_FuR.mjs";
+import { I as outputFlags, K as ConfigError, l as writeJson, u as writeText } from "./cli.mjs";
+import { nt as parseInteger, t as defineMetabaseCommand } from "./runtime-BQiGgbgZ.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 //#region src/commands/uuid.ts
@@ -16,8 +15,7 @@ var uuid_default = defineMetabaseCommand({
 		skill: "mbql",
 		purpose: "where lib/uuid values are used"
 	}],
-	capabilities: null,
-	worktree: "any",
+	requires: null,
 	args: {
 		...outputFlags,
 		count: {

package/dist/{validate-BWchyW0V.mjs → validate-CWd6l6KZ.mjs}

@@ -1,4 +1,4 @@
-import { h as escapeJsonPointerSegment, i as ConfigError, t as isPlainObject } from "./predicates-Bkm2IoeX.mjs";
+import { K as ConfigError, gt as escapeJsonPointerSegment, h as isPlainObject } from "./cli.mjs";
 import { z } from "zod";
 import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";

package/dist/{validate-query-Chc43ezW.mjs → validate-query-Boi8-cAP.mjs}

@@ -1,6 +1,5 @@
-import { i as ConfigError } from "./predicates-Bkm2IoeX.mjs";
-import { m as writeJson } from "./cli.mjs";
-import { i as validateQuery, r as isMbql5Query, t as assertNotLegacyEnvelopeWrappingMbql5 } from "./validate-BWchyW0V.mjs";
+import { K as ConfigError, l as writeJson } from "./cli.mjs";
+import { i as validateQuery, r as isMbql5Query, t as assertNotLegacyEnvelopeWrappingMbql5 } from "./validate-CWd6l6KZ.mjs";
 //#region src/commands/validate-query.ts
 const skipValidateFlag = { "skip-validate": {
 	type: "boolean",

package/dist/{values-BL_U-Zdw.mjs → values-DLwZl-P8.mjs}

@@ -1,6 +1,6 @@
-import { H as profileFlag, R as connectionFlags, V as outputFlags, _ as formatScalar, p as renderSummary } from "./cli.mjs";
-import { t as defineMetabaseCommand } from "./runtime-CNAZ_FuR.mjs";
-import { t as parseId } from "./parse-id-DDCn3VXx.mjs";
+import { I as outputFlags, L as profileFlag, N as connectionFlags, c as renderSummary, f as formatScalar } from "./cli.mjs";
+import { t as defineMetabaseCommand } from "./runtime-BQiGgbgZ.mjs";
+import { t as parseId } from "./parse-id-DR8aUSdL.mjs";
 import { s as FieldValues } from "./field-Cr2DPUG9.mjs";
 import { n as fieldValuesView } from "./field-BPsNa-TO.mjs";
 //#region src/commands/field/values.ts
@@ -9,8 +9,7 @@ var values_default = defineMetabaseCommand({
 		name: "values",
 		description: "Fetch the cached distinct values for a field (FieldValues list)"
 	},
-	capabilities: { minVersion: 58 },
-	worktree: "any",
+	requires: ["field.values"],
 	args: {
 		...outputFlags,
 		...profileFlag,

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

@@ -1,21 +1,6 @@
-import { n as createClient } from "./client-DYD8WZYy.mjs";
-import { f as errorMessage, l as TimeoutError, o as MetabaseError, s as NetworkError } from "./predicates-Bkm2IoeX.mjs";
-import { U as tryParseTag, W as SessionProperties, g as USER_AGENT } from "./runtime-CNAZ_FuR.mjs";
-import { r as HttpError } from "./network-error-D6CiOEBw.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
+import { n as createClient } from "./client-Bv7Iwdvh.mjs";
+import { J as MetabaseError, Y as NetworkError, Z as TimeoutError, et as errorMessage } from "./cli.mjs";
+import { $ as probeServer, L as HttpError, O as USER_AGENT } from "./runtime-BQiGgbgZ.mjs";
 //#region src/core/auth/verify.ts
 const VERIFY_TIMEOUT_MS = 15e3;
 async function verifyAndProbe(url, credential, options = {}) {

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

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

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

@@ -1,9 +1,9 @@
-import { H as profileFlag, R as connectionFlags, U as worktreeFlag, V as outputFlags, p as renderSummary } from "./cli.mjs";
-import { r as WORKTREE_SCOPE_DETAIL, s as scopeQuery, t as defineMetabaseCommand } from "./runtime-CNAZ_FuR.mjs";
-import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-75SvT7Zv.mjs";
-import { r as parseWaitSchedule } from "./wait-flags-DzytMEG8.mjs";
-import { l as syncTaskView } from "./git-sync-LQIVMNxO.mjs";
-import { a as throwIfFailedTask, i as taskPollOptions, n as formatSyncTask, r as syncTaskIdleView, t as SyncTaskOrIdle } from "./sync-task-G1K47Nvn.mjs";
+import { I as outputFlags, L as profileFlag, N as connectionFlags, c as renderSummary } from "./cli.mjs";
+import { t as defineMetabaseCommand } from "./runtime-BQiGgbgZ.mjs";
+import { n as DEFAULT_TIMEOUT_MS, t as DEFAULT_INTERVAL_MS } from "./poll-By46YQ5J.mjs";
+import { r as parseWaitSchedule } from "./wait-flags-DiQ_kRjZ.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({
@@ -11,17 +11,11 @@ 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"
-	},
-	worktree: "scoped",
-	details: WORKTREE_SCOPE_DETAIL,
+	requires: ["gitSync.waitForTask"],
 	args: {
 		...outputFlags,
 		...profileFlag,
 		...connectionFlags,
-		...worktreeFlag,
 		timeout: {
 			type: "string",
 			description: "Polling timeout in ms",
@@ -35,11 +29,9 @@ var wait_default = defineMetabaseCommand({
 	},
 	outputSchema: WaitResult,
 	examples: ["mb git-sync wait", "mb git-sync wait --timeout 300000 --json"],
-	async run({ args, ctx, getClient, getWorktree }) {
+	async run({ args, ctx, getClient }) {
 		const schedule = parseWaitSchedule(args);
-		const mb = await getClient();
-		const scope = await getWorktree();
-		const final = await mb.gitSync.waitForTask(taskPollOptions(schedule), scopeQuery(scope));
+		const final = await (await getClient()).gitSync.waitForTask(taskPollOptions(schedule));
 		if (final === null) {
 			renderSummary({ status: "idle" }, syncTaskIdleView, "No git-sync task is running.", ctx);
 			return;

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

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

package/package.json

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

package/skill-data/core/SKILL.md

@@ -13,7 +13,7 @@ Top-level command groups (run `mb <group> --help` to discover verbs):
 ```
 auth | db | table | field | upload | content-translation | query | card | dashboard | snippet | segment | measure | collection | library
 document | timeline | timeline-event | transform | transform-job | transform-tag | alert | subscription | setting
-search | git-sync | worktree | setup | eid | uuid | upgrade | skills
+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.
@@ -47,8 +47,6 @@ Once a name is established, pass `--profile <name>` to **every** subsequent comm
 
 **`--wait` for async operations.** `transform run`, `git-sync import`, and similar verbs return immediately by default. Pass `--wait` whenever the next step depends on completion — without it you race the operation and see "not ready" / transient connection refusals.
 
-**`--worktree <id|branch>` scopes a command to a git-sync worktree** — an isolated checkout of one branch's content in the same instance (admin-only, v64+). Precedence: flag, then `MB_WORKTREE`, then the profile's pin (`mb worktree pin <ref>` / `unpin`). **The pin is a lock, not a default:** flag and env may only re-state it, a different worktree exits 2 — that is how a harness confines an agent to one worktree. Each command's `worktree` policy shows in `--help --json`: `scoped` honors the scope, `any` ignores it and takes no `--worktree`, `main-only` (`transform run`, main-app writes) refuses under one — report that refusal rather than unpinning. Workflow: the `git-sync` skill.
-
 **Some "lookup" verbs return JSON envelopes, not bare values.** `mb setting get <key>` returns `{"key": "...", "value": ...}`. Extract before reusing:
 
 ```bash
@@ -71,7 +69,7 @@ Every list verb takes `--limit <n>` (items this call returns) and `--offset <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` — 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; …".
+- **`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.
 
 The whole walk, literally:
@@ -106,7 +104,7 @@ mb <noun> create --file ./.scratch/body.json --profile <n> --json
 
 Single-quoted `'EOF'` stops the shell interpolating `$vars` inside the JSON.
 
-Write working files to **`./.scratch`** in the current directory (`mkdir -p ./.scratch` first), never `/tmp` — they persist across the session and the user can review them.
+Write working files to **`./.scratch`** in the current directory (`mkdir -p ./.scratch` first), never `/tmp` — better permissions, they persist across the session, and the user can review them.
 
 ## Discovering commands and schemas
 
@@ -125,27 +123,33 @@ mb transform --help --json | jq -r '.commands[].command'  # verbs under "transfo
 
 ## Resource quirks worth memorizing
 
-Routine verb shapes (list / get / create / update), every flag, and output schemas live in each command's `--help` (add `--json`). Below is only what help does _not_ tell you: footguns and non-obvious behaviors.
+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. Then `table fields <table-id>` per relevant table (bounded: fields are per-table). `--include tables.fields` is the full rollup — small databases only. Hundreds of tables? Traverse by schema (`database schemas <db-id>` → `database schema-tables <db-id> <schema>`) or look tables up by name (`search <term> --models table --db-id <db-id> --limit 10`). `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
-- **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact; `--full` also carries FK targets and dimensions) or use `table fields <id>` (list envelope). `table update` patches table-level metadata only; physical columns aren't editable.
+- **db traversal: the hydration ladder.** Start with `database get <db-id> --include tables` — the compact table map (id, name, schema, description per table), one call that fits most databases. Pick the relevant tables, then `table fields <table-id>` per table (bounded: fields are per-table). `--include tables.fields` is the full rollup — small databases only. Hundreds of tables? Traverse by schema (`database schemas <db-id>` → `database schema-tables <db-id> <schema>`) or look tables up by name (`search <term> --models table --db-id <db-id> --limit 10`). `sync-schema` / `rescan-values` queue async work and return `{status:"ok"}` immediately; `sync-schema --wait` blocks until `initial_sync_status: complete`.
+- **table fields.** `table get` never returns fields on its own — pass `--include fields` (compact; the underlying query_metadata response also carries FK targets and dimensions, visible under `--full`) or use `table fields <id>` (list envelope). `table update` patches table-level metadata only; physical columns aren't editable.
 - **field has no `list`.** Fields are per-table — get them via `table get <id> --include fields`. Never enumerate fields across a whole db (context blow-up). `field summary` is live cardinality `{field_id, count, distincts}`; `field values` is the cached distinct set (`has_more_values: true` ⇒ truncated cache). `field update` patches metadata only (`base_type` isn't editable) — this is where you set a column's `semantic_type` or foreign-key target.
 - **upload (CSV → tables).** `upload csv --file <path>` creates a new table + model (prints `{model_id, table_id}`); `upload append <table-id>` / `upload replace <table-id> --file <path>` add to / overwrite a table **previously created by upload** (columns must match). The destination db+schema is admin-configured, not per-call — check with `mb setting get uploads-settings --json` (`db_id: null` ⇒ uploads off/unconfigured; needs admin to read). `--collection <id|root>` only sets the model's collection. Max 50 MB. Errors: **"The uploads database is not configured."** = no db has uploads enabled; **"Uploads are not enabled."** = the append/replace target isn't an uploaded table.
-- **content-translation.** EE-only (`content_translation` premium feature), admin-only, separate from Remote Sync. `content-translation download > translations.csv` streams the complete active dictionary; `content-translation upload --file translations.csv` replaces every active translation with the file. Always upload the canonical complete CSV, never a partial patch. An empty dictionary downloads as Metabase's four-row sample — don't re-upload it as real translations. Dictionaries are limited to 1.5 MiB.
+<!-- requires: contentTranslation -->
+- **content-translation.** Admin-only, and separate from Remote Sync. `content-translation download > translations.csv` streams the complete active dictionary; `content-translation upload --file translations.csv` replaces every active translation with the file's contents. Always upload the canonical complete CSV, never a partial patch. An empty dictionary downloads as Metabase's four-row sample dictionary — don't re-upload it as real translations. Metabase limits dictionaries to 1.5 MiB.
+<!-- /requires -->
 - **card.** `dataset_query` is the **flat** `mbql/query` value, not a legacy `{type:"query",query:…}` envelope (→ `mbql`). `--export-format csv|xlsx` streams the raw export (pipe to a file), bypassing the JSON envelope. `archive` is the only delete; unarchive with `update --body '{"archived":false}'`. `visualization_settings` keys are scoped by `display` and aren't pre-flighted — see `visualization`.
-- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). Every dashcard must include `card_id`, including existing rows; use `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create` accepts the **same** `dashcards` array in its initial body, so lay out the whole dashboard in one call. `create`/`update` pre-flight every positive `card_id` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a half-width card). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix). Layout patterns and per-chart default sizes → the `dashboard` skill; load it before composing any `dashcards` array.
-- **dashboard parameters (filters).** A dashboard's `parameters` array holds its filter widgets; they're part of the dashboard record, so read them with `dashboard get <id> --fields parameters --json` (no separate verb). **Editing replaces the _whole_ array** (like dashcards), so it's a read-modify-write loop and omitting a parameter deletes it. A parameter only filters a card once it is **mapped** onto that dashcard's `parameter_mappings` — an unmapped parameter is an inert widget. `type` is a **closed enum**; an unlisted value is a hard parse error that echoes the allowed set back. `dashboard parameter-values <id> <parameter-id> [--query <substr>]` fetches a widget's selectable values (`{values, has_more_values}`; `--query` is a case-insensitive substring match). Parameter types, ids, mapping targets, and value sources → the `dashboard` skill; load it before authoring a `parameters` array.
+- **dashboard.** Dashcards round-trip through `PUT /api/dashboard/:id` (no per-dashcard endpoint): `update-dashcard <dash-id> <dashcard-id>` patches one safely; `update --body '{"dashcards":[…]}'` replaces the whole set (omitted ids are deleted server-side; negative ids for new cards). Every dashcard must include `card_id`, including existing rows; use `card_id:null` plus a `visualization_settings.virtual_card` block (`{display:"text"|"heading"|"link"|…}`) for non-question cards. `create` accepts the **same** `dashcards` array in its initial body, so lay out the whole dashboard in one call. `create`/`update` pre-flight every positive `card_id` and exit **2** with `{ok:false,errors:[…]}` on a bad ref (non-bypassable). `dashboard get <id>` (or `--full`) hydrates dashcards/tabs; `list` omits them. **The grid is 24 columns wide:** each dashcard's `{col, row, size_x, size_y}` is in grid units — **full-width is `size_x: 24`** (`size_x: 12` is half a row, the usual cause of a card filling only half the width). Keep `col + size_x ≤ 24`, start a full-width stack's `col` at 0, and don't overlap (the server stores collisions as sent — no auto-fix). Layout patterns and per-chart default sizes → the `dashboard` skill; load it before composing any `dashcards` array.
+- **dashboard parameters (filters).** A dashboard's `parameters` array holds its filter widgets; they're part of the dashboard record, so read them with `dashboard get <id> --fields parameters --json` (no separate verb). **Editing replaces the _whole_ array** (like dashcards), so it's a read-modify-write loop and omitting a parameter deletes it. A parameter only filters a card once it is **mapped** onto that dashcard's `parameter_mappings` — an unmapped parameter is an inert widget. `type` is a **closed enum**; an unlisted value is a hard parse error that echoes the full allowed set back to you. `dashboard parameter-values <id> <parameter-id> [--query <substr>]` fetches a widget's selectable values (`{values, has_more_values}`; `--query` is a case-insensitive substring search). Parameter types, ids, mapping targets, and value sources → the `dashboard` skill; load it before authoring a `parameters` array.
 - **alert / subscription are two unrelated systems.** `alert` watches one **card** and fires on a send condition (`/api/notification`: a cron string, `channel/email`-prefixed handlers, typed recipients); `subscription` delivers one **dashboard** on a schedule (`/api/pulse`: structured `schedule_type` + hour/day/frame, bare `email` channels, `{id}|{email}` recipients). The bodies are not interchangeable. Both silently deliver nowhere if the server has no SMTP / Slack app — check `mb setting get 'email-configured?'` (quote it; the `?` is a shell glob) before creating either. Their list-valued fields (`handlers`/`subscriptions`, `channels`/`cards`) **replace wholesale** on update, so adding one recipient is a read-modify-write. `mb card alerts <id>` and `mb dashboard subscriptions <id>` list what's already attached to a card/dashboard; `archive` deactivates rather than deletes. Load the `notification` skill before authoring either body.
 - **snippet `--archived` is a swap, not a union** — list returns _either_ active _or_ archived rows, never both. (Same for `--filter archived` on dashboard/collection.)
 - **segment / measure.** `update` and `archive` require a non-blank `revision_message` (audit-logged); the CLI does not synthesize it on `update`. `archive` defaults to `"Archived via mb CLI"` — override with `--revision-message`. `definition` is a flat MBQL clause (→ `mbql`): segment = a filter, measure = exactly one aggregation.
-- **timeline / timeline-event.** Timelines are collection-scoped event annotations for time-series charts: a timeline's events render only on time-series questions saved in the **same collection** (`collection_id`; null = root) — sub-collections do **not** inherit, and events never draw on dashboard cards, only in the question (and collection) view. An event draws only when its `timestamp` falls inside the chart's displayed time range. Event `create` requires `timestamp` (ISO 8601), `timezone` (IANA name), `time_matters` (true = the time of day is significant, false = date-only), and `timeline_id` — the API never auto-creates a default timeline (that's UI-only). There is no `timeline-event list`; enumerate with `timeline events <id>` (`--archived` to include archived). Archiving a timeline cascades `archived` to its events; `delete` is a **hard** delete of the timeline and all its events — prefer `archive`.
+- **timeline / timeline-event.** Timelines are collection-scoped event annotations for time-series charts: a timeline's events render only on time-series questions saved in the **same collection** (`collection_id`; null = root) — sub-collections do **not** inherit, and events never draw on dashboard cards, only in the question (and collection) view. To annotate a question's chart, create the timeline in that question's collection, then add events; an event only draws when its `timestamp` falls inside the chart's displayed time range. Event `create` requires `timestamp` (ISO 8601), `timezone` (IANA name), `time_matters` (true = the time of day is significant, false = date-only), and `timeline_id` — the API never auto-creates a default timeline (that's UI-only). There is no `timeline-event list`; enumerate with `timeline events <id>` (`--archived` to include archived). Archiving a timeline cascades `archived` to its events; `delete` is a **hard** delete of the timeline and all its events — prefer `archive`.
 - **collection `<ref>`** accepts four forms only — positive int, `root`, `trash`, or a 21-char entity_id; anything else is a client-side `ConfigError`. `collection items` pages the server endpoint, pulling only as far as the output cap can show — read `has_more`/`next_offset` to continue. `collection tree` is **JSON-only** (`--format text` is rejected). A transform collection needs `collection create --namespace transforms`.
 - **setting set** parses the value as **strict JSON**: a string is `'"value"'` (inner quotes), booleans `true`/`false`, numbers bare. Wrong quoting silently errors — confirm with `setting get <key>` after. `setting get --json` works on every value type (wrapping bare-text responses into `{key, value}`).
 - **search vs. list.** For plain enumeration of cards/dashboards/collections use the dedicated `… list` verbs; reach for `search --models <kind>` only for ranking against a query string or a cross-resource lookup.
+<!-- requires: transforms -->
 - **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`.)
+<!-- /requires -->
 - **setup is one-shot.** `mb setup` walks `/api/setup` for a **fresh** instance only — errors against an already-configured one. Mostly for bootstrapping local / e2e instances.
 - **eid** translates a string entity id → numeric id: `mb eid --model <model> <eid1,eid2> --json`. Entity ids are NanoIDs that can start with `-`, which the positional form misreads as a flag (shell quotes don't help) — for those, use `--body '{"entity_ids":{"card":["-…"]}}'` (the id is a JSON string value, immune to flag parsing).
-- **library.** EE-only (`library` premium feature, v59+). The Library is a curated subtree (`library-data` "Data" + `library-metrics` "Metrics" under a `library` root): tables published to **Data** appear first in data pickers and rank up in search; metrics saved to **Metrics** are prioritized in nav, search, and the query builder — it's how you tell people (and agents) which to start from. `library get` shows the Library and its Data/Metrics collection ids; `library create` provisions it (idempotent). `library publish --table-ids/--db-ids/--schemas` publishes tables into Data — it **resolves the Data collection itself and creates the Library if absent**; each `--schemas` entry is `<db-id>:<schema>` (e.g. `1:public`), not a bare name. `publish` cascades to upstream FK dependencies, `unpublish` to downstream dependents; both need **admin or data-analyst** (Curate alone won't publish) and exit **403** without write **and** query permission on every affected table. `table get`/`table list` carry `is_published` (`collection_id` under `--full`). Good candidates are finished, analysis-ready tables — clean up via transforms first. Publishing does not put the Data collection in the git-sync scope: `mb git-sync add-collection <data-collection-id>` is what makes exports carry the published tables' metadata (see the `git-sync` skill).
+<!-- requires: library -->
+- **library.** 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).
+<!-- /requires -->
 - **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)
@@ -158,12 +162,16 @@ This file is enough for any single-command task. For anything deeper, load the r
 - **`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.
+<!-- requires: transforms -->
 - **`transform`** — transform body JSON, create + run-with-wait, run inspection, tags, jobs.
+<!-- /requires -->
 - **`document`** — Metabase documents (TipTap body, embedding cards).
-- **`git-sync`** — round-tripping content to/from a git remote, and worktrees.
-- **`data-workflow`** — the guided, end-to-end data workflow: investigate raw data, build clean analysis-ready tables, define reusable segments/measures/metrics, answer questions, build dashboards. **Start here when the user states a goal rather than a single verb** — "make sense of my data", "build a data model", "go from raw data to a dashboard", "set up analytics for X". It detects where the data is and routes to the right stage.
+<!-- requires: remoteSync -->
+- **`git-sync`** — round-tripping content to/from a git remote.
+<!-- /requires -->
+- **`data-workflow`** — the guided, end-to-end data workflow: investigate raw data, build clean analysis-ready tables, define reusable segments/measures/metrics, answer questions, build dashboards. **Start here when the user states a goal rather than a single verb** — "make sense of my data", "build a data model", "go from raw data to a dashboard", "be my data analyst", "set up analytics for X". It detects where the data is and routes to the right stage.
 
-If a task spans more than one, load each. `mb skills list` enumerates everything on the installed version.
+If a task spans more than one, load each. `mb skills list` enumerates the skills the profile's server can use, and `mb skills get` prints a skill with the sections that server cannot use left out; `--all` shows everything.
 
 ## Don't
 

package/skill-data/data-workflow/references/building-clean-tables.md

@@ -131,7 +131,7 @@ Then make the links real, not just implied:
 - **Wire foreign keys between your tables.** Mark each linking id as a foreign key pointing at the id it references — set the column's type to foreign-key and its target so Metabase itself knows the tables connect and can traverse them.
 - **Graft onto existing clean data** the user approved (step 3 / Phase 1): point the linking id at the existing table's id the same way. Link, don't duplicate.
 
-**Set the metadata — a transform's output starts blank, and these tables are Library-bound.** A fresh transform table has no descriptions, raw column names, and untyped columns. You worked it out while investigating; don't leave that knowledge stranded in this chat. Set it on the table so the data explains itself inside Metabase (search, the Question editor, Metabot) and is fit to publish. The mechanics — `mb field update` for semantic types / FK targets / display names, `mb table update` for table descriptions, and the feature each edit unlocks — are in the `metadata` skill; the calls about _what_ to set:
+**Set the metadata — a transform's output starts blank, and these tables are the ones people will start from.** A fresh transform table has no descriptions, raw column names, and untyped columns. You worked it out while investigating; don't leave that knowledge stranded in this chat. Set it on the table so the data explains itself inside Metabase (search, the Question editor, Metabot) and is fit to publish. The mechanics — `mb field update` for semantic types / FK targets / display names, `mb table update` for table descriptions, and the feature each edit unlocks — are in the `metadata` skill; the calls about _what_ to set:
 
 - **Semantic types — the highest-value piece.** A column's semantic type is what makes Metabase treat it right: `type/Email`, `type/Currency`/`type/Price`, `type/Category` (turns into a filter dropdown), `type/City`/`type/State`/`type/Country`, `type/CreationTimestamp`, `type/Description`. Set it on every column whose meaning you decoded. A typed column shows money as money, offers a filter dropdown, and lands on the right chart axis for everyone downstream; an untyped one is a guess.
 - **Descriptions.** A one-line description on each table and every non-obvious column.
@@ -165,7 +165,11 @@ Then report plainly:
 
 End on that connection map: it's what the user reads to trust the result, and what lets whatever they build next join on the right ids instead of guessing.
 
-These clean tables are exactly what belongs in the **Library** — published tables appear first when anyone picks a data source, so people start from your curated set, not the raw source. If the user wants that, publish the polished tables to the Library (`mb library publish` / `mb library create` mechanics, premium feature, and permissions are in `core`). Defining reusable segments / measures / metrics on top is the **reusable-definitions** stage (`references/reusable-definitions.md` in this skill).
+<!-- requires: library -->
+
+These clean tables are exactly what belongs in the **Library** — published tables appear first when anyone picks a data source, so people start from your curated set, not the raw source. If the user wants that, publish the polished tables to the Library (`mb library publish` / `mb library create` mechanics and permissions are in `core`). Defining reusable segments / measures / metrics on top is the **reusable-definitions** stage (`references/reusable-definitions.md` in this skill).
+
+<!-- /requires -->
 
 ---
 

package/skill-data/data-workflow/references/reusable-definitions.md

@@ -50,7 +50,9 @@ Two things never bend in any mode: when genuinely unsure, **ask** (the Shared Co
   - "Let me add up revenue the same way everywhere, on this table" → a **measure** on the table.
   - "Revenue is an _official company number_ people pull onto dashboards" → a **metric** in a collection, with a default month-by-month view so it charts cleanly. Lean: make it a metric when it's a headline figure the org reuses across many questions/dashboards; keep it a measure when it's a table-local convenience.
 - **Where the metric lives.** Metrics sit in a collection (folder). Lean: put the org's blessed ones in the shared **Library** so they surface prominently; keep experimental ones in a working collection until trusted.
-- **Publish the official tables to the Library.** The clean, analysis-ready tables your definitions sit on are the org's official starting points — the **Library** is how you mark them as such. Tables published to the Library's **Data** section appear _first_ when anyone picks a data source, nudging people toward your curated tables instead of raw warehouse ones. Lean: publish the wide clean tables you built the semantic layer on; hold back raw or half-built ones. Surface which tables you'd publish and confirm. (Library is a Pro/Enterprise feature; only admins and data analysts can publish — mechanics in `core`.)
+<!-- requires: library -->
+- **Publish the official tables to the Library.** The clean, analysis-ready tables your definitions sit on are the org's official starting points — the **Library** is how you mark them as such. Tables published to the Library's **Data** section appear _first_ when anyone picks a data source, nudging people toward your curated tables instead of raw warehouse ones. Lean: publish the wide clean tables you built the semantic layer on; hold back raw or half-built ones. Surface which tables you'd publish and confirm. (Only admins and data analysts can publish — mechanics in `core`.)
+<!-- /requires -->
 - **Default time dimension for a metric.** A monthly default makes it chart nicely on a dashboard, but doesn't lock anyone out of other groupings. Lean: set a sensible default (usually month) for anything headline; leave it off for raw counts that aren't inherently time-series.
 - **How strict a segment is.** "Active" = last 30 vs 90 days is a real business call with no right answer from the data alone. Lean: surface the few reasonable thresholds with how many rows each catches, let the user pick.
 
@@ -101,7 +103,9 @@ Build each agreed definition. The verb mechanics (create/update flags, the `revi
 - **Segment** → `mb segment create`. A flat MBQL filter clause on a table.
 - **Measure** → `mb measure create`. **Exactly one** aggregation on a table.
 - **Metric** → `mb card create` with the metric shape (`type: "metric"`) — it lives in a **collection**, carries the aggregation plus an optional default time dimension. Put org-blessed ones in the Library collection.
+<!-- requires: library -->
 - **Publish the official tables** → `mb library create` then `mb library publish` (mechanics in `core`) to move the clean tables your definitions sit on into the Library's **Data** section, so people start from your curated set, not raw warehouse tables.
+<!-- /requires -->
 
 Then **verify what the user can't see**, before you hand back:
 
@@ -122,10 +126,14 @@ Then **stop. Hard gate — every mode, no exceptions.** Recap in plain language
 >
 > **Metric** (in your **Library**, charts by month):
 > • **Monthly recurring revenue**
->
+
+<!-- requires: library -->
+
 > **Published to the Library** (these now show up first when anyone picks a data source):
 > • **Customers**, **Orders**
->
+
+<!-- /requires -->
+
 > Open any of those tables' Filter or Summarize block in Metabase to see them in place and try one — give it a look before you start building dashboards on top.
 
 End on that plain-language map. It's what the user reads to trust the result — and it's what stops a wrong definition from quietly propagating into everything built next.

package/skill-data/document/SKILL.md

@@ -81,7 +81,10 @@ Every node is `{ "type": string, "attrs"?: object, "content"?: [nodes], "text"?:
 - **`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`, `user`, `action`, `indexed-entity` (plus `measure` on v60+).
+- **`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`, `user`, `action`, `indexed-entity`.
+  <!-- requires: smartLinkMeasureModel -->
+  - `measure` is a valid `model` too.
+  <!-- /requires -->
 - **`metabot`** — an inline Metabot prompt block.
 
 ## Embedding an existing card

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

@@ -1,7 +1,8 @@
 ---
 name: git-sync
-description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections, Library-published table/field metadata) between an instance and a git remote via `mb git-sync …` — status, dirty / has-remote-changes checks, import, export (with branch guard), branches, stash, add/remove a collection from sync. Load when the user wants to "import the latest changes", "export to git", "push my changes to the repo", "open a PR with my Metabase changes", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …` / `mb worktree …`. Also covers worktrees — isolated per-branch checkouts of transforms and other content — for "work on this branch in isolation", "create a worktree", "pin the profile to a worktree", "export the worktree and open a PR".
+description: Round-trip Metabase content (cards, dashboards, transforms, snippets, collections, Library-published table/field metadata) between an instance and a git remote via `mb git-sync …` — status, dirty / has-remote-changes checks, import, export (with branch guard), branches, stash, add/remove a collection from sync. Load when the user wants to "import the latest changes", "export to git", "push my changes to the repo", "open a PR with my Metabase changes", "git sync", "dirty check", "stash before pulling", "add a collection to sync", or anything `mb git-sync …`.
 allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+requires: [remoteSync]
 ---
 
 # git-sync (representations ↔ instance)
@@ -40,7 +41,6 @@ Pulls the configured branch and applies it to the instance. Polls until the task
 | `--branch <name>` | Defaults to the `remote-sync-branch` setting; override per-call.                     |
 | `--no-wait`       | Return as soon as the task is queued; combine with `mb git-sync wait` later.         |
 | `--force`         | **Discards local Metabase-side dirty changes** (lossy). Confirm with the user first. |
-| `--merge`         | Three-way merge remote changes instead of failing on divergence. Confirm first.      |
 | `--timeout <ms>`  | Polling deadline. Default 600 000.                                                   |
 | `--interval <ms>` | Polling cadence. Default 2 000.                                                      |
 
@@ -63,7 +63,6 @@ Pushes Metabase-side changes back to the configured remote. `-m` is the commit m
 | `--branch <name>`   | Push to a specific branch instead of the configured one. |
 | `-m, --message <s>` | Commit message.                                          |
 | `--force`           | Force-push / overwrite remote. Confirm with the user.    |
-| `--merge`           | Three-way merge instead of failing on divergence.        |
 | `--no-wait`         | Don't poll.                                              |
 
 Workflow:
@@ -98,94 +97,6 @@ mb git-sync stash --profile <n>                           # export current state
 
 `stash` is the safe move when the instance has team work you don't want to lose, but you need to pivot to a different branch (`import` would discard, `export --force` would overwrite). It exports current state to a fresh branch first.
 
-## Worktrees (isolated branch checkouts)
-
-A **worktree** is a self-contained checkout of one branch's content inside the same instance. Transforms, transform tags, snippets, `transforms`-namespace collections, the Library, cards, dashboards, and documents are tagged with the worktree's id; tables and fields stay shared with the main app. It is how a chain of transforms gets built, exported, and reviewed as a PR without touching production content. Admin-only, and needs Metabase v64+ with the `remote_sync` feature.
-
-Two hard limits, up front:
-
-- **A worktree's transforms cannot be run.** `mb transform run` refuses while a worktree scope is in force, and the server rejects the run anyway. There is no workaround to find — run the transform in the main app after the branch is merged and imported, and say so rather than trying to validate the SQL by running it in the worktree.
-- **A worktree is bound to its branch for life.** No branch switching inside one; a different branch means a different worktree.
-
-### Where am I? Check before touching import/export
-
-```bash
-mb auth status --profile <n> --json | jq '.worktree'      # {id, branch} when the profile is pinned, else null
-mb git-sync status --profile <n> --json | jq '.worktree'  # the scope this command ran under
-mb worktree list --profile <n> --json                     # every worktree on the instance
-```
-
-A pinned profile pushes to the worktree's branch; an unpinned one pushes to whatever `remote-sync-branch` points at. Confusing the two is how worktree work lands on the team's tracked branch, so read the pin before the first `export`.
-
-### Preconditions before creating one
-
-1. **The user named the branch.** Create a worktree only for a branch the user asked you to work on.
-2. **A branch holds at most one worktree.** Check `mb worktree list --json` first; a duplicate fails with the server's `A worktree for branch '<b>' already exists.` — reuse it with `mb worktree pin <branch>` instead.
-3. **A pinned profile is already confined.** `mb worktree create` for any other branch is refused, because a second worktree from a pinned session would escape the pin.
-
-### The workflow
-
-```bash
-# 1. Create the worktree and pin the profile to it. Mints the branch on the remote when missing
-#    (--no-checkout, so the main app's tracked branch is untouched), then pulls the branch in.
-mb worktree create feat/order-metrics --pin --profile <n> --json
-
-# 2. Edit transforms. Scoped commands need no extra flag once the profile is pinned.
-mb transform create --file ./.scratch/transform.json --profile <n> --json
-mb transform list --profile <n> --json        # only this worktree's transforms
-mb transform update <id> --file ./.scratch/patch.json --profile <n> --json
-
-# 3. Read state before pushing — same rule as the main app.
-mb git-sync status --profile <n> --json       # branch, dirty flag, current task, all scoped
-mb git-sync dirty  --profile <n> --json       # exactly what will be committed
-
-# 4. Dry-run the push, read the answer, then push.
-mb git-sync export-preflight --profile <n> --json
-mb git-sync export -m "add order metrics transforms" --profile <n>
-
-# 5. Open the PR from the branch with plain git / gh, and let a human review and merge it.
-
-# 6. Retire the worktree once the PR is merged. This clears the pin it was holding.
-mb worktree delete feat/order-metrics --profile <n> --json
-```
-
-`export-preflight` answers `{has_changes, clean, conflicts, summary: {added, updated, removed}, force_push_casualties: {deleted, overwritten}, reason}`. Read it before every worktree export: `clean: true` with empty `conflicts` is a push that applies as-is; a non-empty `conflicts` or `force_push_casualties` is a conversation with the user, not a `--force`.
-
-The main app pulls the merged branch from a **different, unpinned** profile — `git-sync import` into the main app and `transform run` are both main-app operations and a pinned profile refuses them:
-
-```bash
-mb git-sync import --profile <main-app-profile>
-mb transform run <id> --wait --profile <main-app-profile> --json
-```
-
-### Scope precedence and what a pinned profile refuses
-
-The scope comes from `--worktree <id|branch>`, else `MB_WORKTREE`, else the profile's pin. **The pin is a lock, not a default:** while it stands, the flag and the env var may only re-state it, and naming a different worktree exits 2 with `profile "<p>" is pinned to worktree <id> (<branch>); refusing --worktree <x>`.
-
-Under a scope, a command that changes or runs main-app state refuses before any request and exits 2 — `transform run` / `cancel`, `card` / `library` writes, and the main-app git-sync verbs `stash`, `create-branch`, `add-collection`, `remove-collection`:
-
-```
-transform run is not available inside a worktree (scope: worktree 3 (feat/order-metrics) from the profile pin); it changes main-app content. Unpin the profile (`mb worktree unpin`) or drop MB_WORKTREE to run it against the main app.
-```
-
-Two more refusals belong to the scope:
-
-- Fetching a row that lives elsewhere: `transform 12 is not in worktree 3 (feat/order-metrics); refusing to touch main-app content`.
-- `--branch` on `import` / `export` / `export-preflight`: `a worktree is pinned to its branch; drop --branch`.
-
-### Confirmations these flags need
-
-- `--force` (on `import`, `export`, and `worktree delete`) and `--merge` (on `import` / `export`) are **lossy or history-rewriting** — ask the user first, with `AskUserQuestion`, naming what gets discarded. `export-preflight`'s `force_push_casualties` is the list to show them.
-- `mb worktree delete` refuses a worktree holding unpushed changes: `worktree <id> (<branch>) has unpushed changes; push them with mb git-sync export or pass --force to discard`. Export first, or ask before forcing — the content in a worktree exists nowhere else once it is gone.
-
-### Don't (worktrees)
-
-- **Don't unpin to reach the main app.** The pin is the isolation boundary a harness put there; `mb worktree unpin` to get past a refusal turns an isolated session into one that can write production content. Report the refusal and what you would need instead.
-- **Don't run a worktree's transforms**, and don't route around the refusal with `mb query`, a native card, or a second profile. Validate the query shape with `--dry-run` (see `mbql`) and run it for real in the main app after the merge.
-- **Don't create worktrees for branches you were not asked to touch.** A worktree checks a whole branch's content into the instance; an unwanted one is content to clean up, not a free experiment.
-- **Don't `git-sync export` from the main app while the work lives in a worktree.** It pushes the main app's state to the tracked branch and the worktree's edits are not in it. Check `.worktree` in `git-sync status` before exporting.
-- **Don't hand-write the branch's YAML in the repo to "help" the PR.** Worktree content round-trips through `export` exactly like main-app content — see the first entry of the general "Don't" list below.
-
 ## Polling and cancelling
 
 ```bash
@@ -220,6 +131,8 @@ mb setting set remote-sync-type '"read-write"' --profile <n>
 
 **Verifying the result.** `mb git-sync status --profile <n> --json` lists the flagged collections under `synced_collections`, and `mb collection get <id> --json` shows the per-collection `is_remote_synced` flag.
 
+<!-- requires: library -->
+
 ## Published table metadata (Library) and sync scope
 
 Table and field metadata — table/field descriptions, semantic types (`type/PK`, `type/FK`), FK targets, plus segments and measures on the table — serializes for **Library-published tables only**, under `databases/<db>/schemas/<schema>/tables/<table>/…` in the repo. Eligibility is two-gated: the table must be published (`mb library publish`), **and** the Library collection holding it must itself carry `is_remote_synced: true`. An ordinary warehouse table, or a transform's target table that isn't published, never serializes — a transform's YAML carries only the transform definition (query, target, description), not the output table's field metadata.
@@ -234,6 +147,8 @@ mb git-sync stash --new-branch <branch> -m "..." --profile <n>     # or create-b
 
 Flagging the collection records it for the next export, which serializes its current content — including already-published tables and their field metadata. `mb library publish` prints a reminder when the target collection is outside the sync scope on an instance with a configured remote.
 
+<!-- /requires -->
+
 ## Don't (git-sync-specific)
 
 - Don't turn instance-side changes into hand-written repo files. When the changes were made against the instance, export them (`stash` / `create-branch` + `export`) and PR the exported branch; reconstructing them as YAML by hand — or pushing files in paths/formats the serializer doesn't own — produces content that never applies on import, and pushing behind Metabase's back races its own sync tasks. Hand-editing YAML belongs to the repo-first workflow, in the serialized layout the repo already uses.

package/skill-data/mbql/SKILL.md

@@ -122,7 +122,7 @@ No `type:"query"` wrapper, no `query:` nesting. If you wrap the query inside a l
 
 ## Legacy formats you may encounter
 
-Older Metabase servers used a different query envelope (sometimes called MBQL 4 / "legacy MBQL"); the `mbql/query` shape above is what recent servers store and return. You won't author the legacy shapes, but you may see them in queries created long ago. Anything not `lib/type: "mbql/query"` is sent as-is and normalized server-side — you lose validation, so don't author these:
+Queries created long ago may carry a different envelope (sometimes called MBQL 4 / "legacy MBQL"); the `mbql/query` shape above is what the server stores and returns. You won't author the legacy shapes, but you may see them in old content. Anything not `lib/type: "mbql/query"` is sent as-is and normalized server-side — you lose validation, so don't author these:
 
 - **Legacy structured** — `{ "type": "query", "database": N, "query": { "source-table": T, … } }`
 - **Flat native** — `{ "type": "native", "database": N, "native": { "query": "SELECT …" } }` — the server accepts it, but author the native stage instead (`native-sql`).