busa-cli 0.19.0 → 0.19.2

package/dist/{run-FjzYcGKi.js → run-ZDakuDNP.js}

@@ -56,7 +56,7 @@ const OPERATIONS$1 = [
 * audience, the exact silent-drop failure the server-side rejection exists to
 * end. `params.appliesWhen` still documents which operations accept it.
 */
-const mergeIntent$4 = (input) => {
+const mergeIntent$5 = (input) => {
 	if (input.requireReview) return { autoMerge: false };
 	if (input.autoMerge) return { autoMerge: true };
 	return {};
@@ -246,7 +246,7 @@ const baseFieldChangeTask = {
 			baseId: input.baseId,
 			...input.message ? { message: input.message } : {},
 			...input.submittedBy ? { submittedBy: input.submittedBy } : {},
-			...mergeIntent$4(input)
+			...mergeIntent$5(input)
 		};
 		switch (input.operation) {
 			case "add": return client.bases.fieldChangeRequest({
@@ -629,7 +629,7 @@ const nodeReadFileTask = {
 * A batch containing a `delete` is review-first server-side no matter what this
 * sends, so don't imply otherwise in the flag's description.
 */
-const mergeIntent$3 = (input) => {
+const mergeIntent$4 = (input) => {
 	if (input.requireReview) return { autoMerge: false };
 	if (input.autoMerge) return { autoMerge: true };
 	return {};
@@ -699,7 +699,7 @@ const nodeFilesChangeRequestTask = {
 			operations: input.operations,
 			...input.message ? { message: input.message } : {},
 			...input.submittedBy ? { submittedBy: input.submittedBy } : {},
-			...mergeIntent$3(input)
+			...mergeIntent$4(input)
 		};
 		return client.fileTrees.createChangeRequest(payload);
 	}
@@ -1424,7 +1424,7 @@ const rejectMismatchedPayload = (input) => {
 	if (wrong.length > 0) throw new Error(`${wrong.join(", ")} ${wrong.length > 1 ? "are" : "is"} not valid for --type ${type}.`);
 };
 /** `autoMerge` is tri-state: unset (permission-aware default), forced on, forced off. */
-const mergeIntent$2 = (input) => {
+const mergeIntent$3 = (input) => {
 	if (input.requireReview) return { autoMerge: false };
 	if (input.autoMerge) return { autoMerge: true };
 	return {};
@@ -1637,7 +1637,7 @@ const nodeCreateTask = {
 			name: input.name,
 			description: input.description,
 			parentNodeId: input.parentNodeId,
-			...mergeIntent$2(input)
+			...mergeIntent$3(input)
 		};
 		if (FILE_TREE_TYPES.has(type)) {
 			const payload = {
@@ -1675,7 +1675,7 @@ const nodeCreateTask = {
 		return client.nodes.createChangeRequest({
 			message: input.message ?? `Create ${type} ${input.name}`,
 			submittedBy: input.submittedBy,
-			...mergeIntent$2(input),
+			...mergeIntent$3(input),
 			operations: [{
 				kind: "create",
 				nodeType: type,
@@ -1688,6 +1688,74 @@ const nodeCreateTask = {
 	}
 };
 //#endregion
+//#region ../../packages/busabase-contract/src/tasks/record-bulk-update.ts
+const mergeIntent$2 = (input) => {
+	if (input.requireReview) return { autoMerge: false };
+	if (input.autoMerge) return { autoMerge: true };
+	return {};
+};
+const recordBulkUpdateTask = {
+	name: "record_bulk_update_change_request",
+	cliPath: ["records", "bulk-update-change-request"],
+	summary: "Propose partial updates to many records in one ChangeRequest",
+	guidance: "All updates must target active records in the same Base. Each recordId may appear once. Each fields object is a partial update: omitted keys stay unchanged and null clears a field. The batch is reviewed and merged atomically. Use baseCommitId per update when the caller must pin the version it read. Review is permission-aware; pass requireReview to force a pending ChangeRequest even when the key has write access.",
+	annotations: {
+		readOnly: false,
+		destructive: false
+	},
+	params: [
+		{
+			name: "baseId",
+			kind: "string",
+			required: true,
+			description: "Base owning every record."
+		},
+		{
+			name: "updates",
+			kind: "json",
+			required: true,
+			description: "JSON array of {recordId, fields, baseCommitId?, message?}, e.g. [{\"recordId\":\"rec_1\",\"fields\":{\"status\":\"published\"}}]."
+		},
+		{
+			name: "message",
+			kind: "string",
+			description: "Reviewer-facing message for the batch."
+		},
+		{
+			name: "submittedBy",
+			kind: "string",
+			description: "Producer label recorded on the change."
+		},
+		{
+			name: "idempotencyKey",
+			kind: "string",
+			description: "Retry key scoped to this Base and submitter."
+		},
+		{
+			name: "autoMerge",
+			kind: "boolean",
+			description: "Apply immediately when the actor has write access."
+		},
+		{
+			name: "requireReview",
+			kind: "boolean",
+			description: "Force one pending ChangeRequest even when the actor has write access."
+		}
+	],
+	examples: ["busabase-cli records bulk-update-change-request --base-id bas_1 --updates-json '[{\"recordId\":\"rec_1\",\"fields\":{\"status\":\"published\"}}]' --require-review", "busabase-cli records bulk-update-change-request --base-id bas_1 --updates-json @updates.json --idempotency-key august-review-v1"],
+	execute: async (client, input) => {
+		if (!Array.isArray(input.updates)) throw new Error("`updates` must be a JSON array.");
+		return client.bases.createBulkUpdateChangeRequest({
+			baseId: input.baseId,
+			updates: input.updates,
+			...input.message ? { message: input.message } : {},
+			...input.submittedBy ? { submittedBy: input.submittedBy } : {},
+			...input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {},
+			...mergeIntent$2(input)
+		});
+	}
+};
+//#endregion
 //#region ../../packages/busabase-contract/src/tasks/record-change.ts
 /**
 * Changing an existing record: update, delete (archive), or restore — one task
@@ -1905,7 +1973,7 @@ const recordQueryTask = {
 	examples: [
 		"busabase-cli records query --base-id bas_123 --limit 100",
 		"busabase-cli records count --base-id bas_123",
-		"busabase-cli records count --base-id bas_123 --filters '[{\"fieldSlug\":\"branch\",\"fieldType\":\"text\",\"operator\":\"equals\",\"value\":\"main\"}]'",
+		"busabase-cli records count --base-id bas_123 --filters-json '[{\"fieldSlug\":\"branch\",\"fieldType\":\"text\",\"operator\":\"equals\",\"value\":\"main\"}]'",
 		"busabase-cli records count --base-id bas_123 --view-id viw_456"
 	],
 	execute: async (client, input) => {
@@ -2120,11 +2188,60 @@ const BUSABASE_TASKS = [
 	changeRequestMergeTask,
 	baseFieldChangeTask,
 	recordChangeTask,
+	recordBulkUpdateTask,
 	viewChangeTask,
 	nodePermissionTask,
 	nodeShareTask,
 	listArchivedTask
 ];
+/**
+* Endpoint-level MCP tools fully covered by a task above, keyed by the tool name
+* the OpenAPI generator produces. The MCP adapter excludes these so a catalog
+* carries one way to do each job rather than two.
+*
+* Kept as tool names (not contract paths) because that is what the MCP layer
+* filters on, and it is the name an agent would actually have seen.
+*
+* NOT listed on purpose:
+*   - `nodes_create_change_request` — `node_create` covers only a single `create`
+*     operation. The endpoint also does `rename`, and composes several operations
+*     into one change request (`ref`/`parentNodeRef` builds a whole subtree
+*     atomically). Excluding it would be a capability regression, not a cleanup.
+*   - `forms_create` — configures an existing node, so it is a second step after
+*     `node_create --type form`, not a duplicate of it.
+*   - `nodes_purge` — permanent delete is a genuinely different operation from
+*     `node_archive`, and `node_archive`'s guidance now tells an agent when each
+*     one applies.
+*/
+const TASK_SUPERSEDED_MCP_TOOLS = [
+	"file_trees_create",
+	"docs_create",
+	"bases_create",
+	"files_create",
+	"records_search",
+	"file_trees_list_files",
+	"file_trees_read_file",
+	"file_trees_create_change_request",
+	"records_list",
+	"records_count",
+	"change_requests_list",
+	"change_requests_counts",
+	"change_requests_review",
+	"change_requests_review_many",
+	"change_requests_merge",
+	"change_requests_merge_many",
+	"bases_field_change_request",
+	"records_change_request",
+	"bases_create_bulk_update_change_request",
+	"views_change_request",
+	"nodes_principals_list",
+	"nodes_principals_add",
+	"nodes_principals_remove",
+	"nodes_share_get",
+	"nodes_share_set",
+	"nodes_share_disable",
+	"bases_list_deleted_fields"
+];
 //#endregion
 //#region src/config-file.ts
 /**
@@ -3269,15 +3386,168 @@ function banner(baseUrl) {
 	return out.join("\n");
 }
 //#endregion
+//#region src/errors.ts
+/**
+* Process exit code per class.
+*
+* `1` stays the code for an unclassified error, so a script testing `!= 0` is
+* unaffected and only a script testing `== 1` sees a change.
+*/
+const EXIT_CODES = {
+	ERROR: 1,
+	USAGE: 2,
+	UNAUTHORIZED: 3,
+	FORBIDDEN: 3,
+	NOT_FOUND: 4,
+	VALIDATION: 5,
+	CONFLICT: 6,
+	RATE_LIMITED: 7,
+	SERVER_ERROR: 8,
+	NETWORK: 9,
+	REVIEW_REJECTED: 10,
+	TIMEOUT: 11
+};
+const RETRYABLE = /* @__PURE__ */ new Set([
+	"RATE_LIMITED",
+	"SERVER_ERROR",
+	"NETWORK"
+]);
+/** `data.issues` as the server sends it, flattened. Shared with `explainError`'s prose rendering. */
+function toIssues(raw) {
+	if (!Array.isArray(raw) || raw.length === 0) return void 0;
+	const issues = raw.map((issue) => {
+		if (!issue || typeof issue !== "object") return {
+			path: "",
+			message: String(issue)
+		};
+		const { path, message } = issue;
+		return {
+			path: Array.isArray(path) ? path.join(".") : typeof path === "string" ? path : "",
+			message: String(message ?? issue)
+		};
+	});
+	return issues.length > 0 ? issues : void 0;
+}
+const codeForStatus = (status) => {
+	if (status === 401) return "UNAUTHORIZED";
+	if (status === 403) return "FORBIDDEN";
+	if (status === 404) return "NOT_FOUND";
+	if (status === 409) return "CONFLICT";
+	if (status === 429) return "RATE_LIMITED";
+	if (status === 400 || status === 422) return "VALIDATION";
+	if (status >= 500) return "SERVER_ERROR";
+	return "ERROR";
+};
+/**
+* A transport failure never reaches the server, so it has no status to read.
+* Node reports every one of them as a bare `TypeError: fetch failed` with the
+* real reason on `.cause`, which is why this matches on text rather than type.
+*/
+const isNetworkFailure = (message) => /fetch failed|econnrefused|enotfound|getaddrinfo|econnreset|etimedout|socket hang up|network/i.test(message);
+/**
+* `rawFetch` (health / openapi / `api` passthrough) throws a plain `Error`
+* carrying `HTTP <status> <statusText>: …` rather than an `ORPCError`, so the
+* status has to be read back out of the message for those paths.
+*/
+const statusFromMessage = (message) => {
+	const match = /\bHTTP (\d{3})\b/.exec(message);
+	return match ? Number(match[1]) : void 0;
+};
+/** Classify any thrown value into the stable shape above. Never throws. */
+function classifyError(error) {
+	const message = error instanceof Error ? error.message : String(error);
+	const outcome = error?.cliCode;
+	if (typeof outcome === "string" && outcome in EXIT_CODES) {
+		const code = outcome;
+		return {
+			code,
+			message,
+			retryable: RETRYABLE.has(code),
+			exitCode: EXIT_CODES[code]
+		};
+	}
+	const issues = toIssues(error?.data?.issues);
+	const status = typeof error?.status === "number" ? error.status : statusFromMessage(message);
+	let code;
+	if (status !== void 0) code = codeForStatus(status);
+	else if (isNetworkFailure(message)) code = "NETWORK";
+	else code = "ERROR";
+	const orpcCode = error?.code;
+	if (code === "ERROR" && typeof orpcCode === "string") {
+		if (orpcCode === "NOT_FOUND") code = "NOT_FOUND";
+		else if (orpcCode === "UNAUTHORIZED") code = "UNAUTHORIZED";
+		else if (orpcCode === "FORBIDDEN") code = "FORBIDDEN";
+		else if (orpcCode === "CONFLICT") code = "CONFLICT";
+		else if (orpcCode === "BAD_REQUEST" || orpcCode === "UNPROCESSABLE_CONTENT") code = "VALIDATION";
+		else if (orpcCode === "TOO_MANY_REQUESTS") code = "RATE_LIMITED";
+	}
+	return {
+		code,
+		...status !== void 0 ? { status } : {},
+		message,
+		...issues ? { issues } : {},
+		retryable: RETRYABLE.has(code),
+		exitCode: EXIT_CODES[code]
+	};
+}
+/** The stdout envelope for a failed command under `--output json`. */
+function errorEnvelope(classified) {
+	return {
+		ok: false,
+		code: classified.code,
+		...classified.status !== void 0 ? { status: classified.status } : {},
+		message: classified.message,
+		...classified.issues ? { issues: classified.issues } : {},
+		retryable: classified.retryable
+	};
+}
+/**
+* A command that ran fine but ended in an outcome the caller must branch on —
+* a proposal a reviewer turned down, or a `--wait` that ran out of budget.
+*
+* Carries its own class so {@link classifyError} does not have to guess from a
+* message, and so the envelope reports it exactly like any other failure.
+*/
+var CliOutcomeError = class extends Error {
+	cliCode;
+	constructor(cliCode, message) {
+		super(message);
+		this.name = "CliOutcomeError";
+		this.cliCode = cliCode;
+	}
+};
+//#endregion
 //#region src/format.ts
 /** Render a command result as JSON, a compact text view, or an aligned table. */
 function render(value, output) {
 	if (output === "json") return JSON.stringify(value, null, 2);
 	if (output === "text") return renderText(value);
 	if (Array.isArray(value)) return renderTable(value);
+	const envelope = asEnvelope(value);
+	if (envelope) return renderEnvelope(envelope, renderTable);
 	if (value && typeof value === "object") return renderRecord(value);
 	return String(value);
 }
+function asEnvelope(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const entries = Object.entries(value);
+	const arrays = entries.filter((entry) => Array.isArray(entry[1]));
+	if (arrays.length !== 1) return void 0;
+	const meta = entries.filter(([, item]) => !Array.isArray(item));
+	if (!meta.every(([, item]) => item === null || item === void 0 || typeof item !== "object")) return void 0;
+	return {
+		key: arrays[0][0],
+		rows: arrays[0][1],
+		meta
+	};
+}
+function renderEnvelope(envelope, renderRows) {
+	const body = envelope.rows.length === 0 ? `(no ${envelope.key})` : renderRows(envelope.rows);
+	const meta = envelope.meta.filter(([, item]) => item !== null && item !== void 0);
+	if (meta.length === 0) return body;
+	const width = Math.max(...meta.map(([key]) => key.length));
+	return `${body}\n\n${meta.map(([key, item]) => `${key.padEnd(width)}  ${cell(item)}`).join("\n")}`;
+}
 function cell(value) {
 	if (value === null || value === void 0) return "";
 	if (typeof value === "object") return compactJson(value);
@@ -3320,6 +3590,8 @@ function renderTable(rows) {
 	].join("\n");
 }
 function renderText(value) {
+	const envelope = asEnvelope(value);
+	if (envelope) return renderEnvelope(envelope, renderText);
 	if (Array.isArray(value)) {
 		if (value.length === 0) return "(no rows)";
 		if (isNodeTree(value)) return renderNodeTree$1(value);
@@ -3369,6 +3641,48 @@ function nodeIcon(type) {
 		default: return "[node]";
 	}
 }
+/**
+* Drop hydrated parents from a result, keeping the id that points at them.
+*
+* A record VO is ~4.5 KB, of which 3.6 KB is a full copy of its parent `base`
+* — repeated identically on every row, so ten records cost 151 KB and nine
+* copies of that Base are pure waste to any caller that already knows which
+* Base it asked about. `createdByUser` and `headCommit` are the same pattern.
+*
+* The test for "this is a hydration, not content" is deliberately structural
+* rather than a list of field names, so it does not rot as VOs change: an
+* object-valued key is dropped only when a sibling STRING key already
+* identifies the same thing — `base`/`baseId`, `headCommit`/`headCommitId`,
+* `createdByUser`/`createdBy`. Nothing that lacks such a sibling is touched,
+* which is why a Base's `fields`, a node's `children`, and `whoami`'s `space`
+* all survive: dropping those would remove the answer, not a duplicate.
+*/
+function slim(value) {
+	if (Array.isArray(value)) return value.map(slim);
+	if (!value || typeof value !== "object") return value;
+	const row = value;
+	const scalarKeys = Object.entries(row).filter(([, item]) => typeof item === "string").map(([key]) => key);
+	const out = {};
+	for (const [key, item] of Object.entries(row)) {
+		if (isHydrated(key, item, scalarKeys)) continue;
+		out[key] = slim(item);
+	}
+	return out;
+}
+/**
+* `carriesPayload` is the guard that stops this from eating the answer. A
+* record's `headCommit` is structurally indistinguishable from its `base` — an
+* object whose `id` is already on the row as `headCommitId` — but it is where
+* the record's FIELD VALUES live (`headCommit.payload`), so dropping it would
+* return ten rows of ids and no data. Every commit-shaped object in this
+* contract carries `payload`; no hydrated parent does.
+*/
+const isHydrated = (key, item, scalarKeys) => {
+	if (item === null || typeof item !== "object") return false;
+	if (carriesPayload(item)) return false;
+	return scalarKeys.some((scalar) => scalar !== key && (scalar === `${key}Id` || key.startsWith(scalar)));
+};
+const carriesPayload = (item) => Array.isArray(item) ? item.some((entry) => entry !== null && typeof entry === "object" && carriesPayload(entry)) : "payload" in item;
 //#endregion
 //#region ../../packages/busabase-contract/src/auth/device-authorization.ts
 /** Public client identifier shared by the Busabase CLI and Cloud auth server. */
@@ -4545,8 +4859,7 @@ z.discriminatedUnion("operation", [archiveBaseInputSchema.extend({
 * when a node carries no `icon`, every host falls back to the type icon, same
 * as before this field existed.
 *
-* The `attachment` variant mirrors buda's `NodeLogo` shape (see
-* `apps/buda/src/domains/agent-controller/components/use-logo-crop-upload.tsx`):
+* The `attachment` variant follows the shared avatar-cropping model:
 * `url`/`attachmentId` are the CROPPED display image actually rendered, while
 * `originalUrl`/`originalAttachmentId` + `crop` are kept so the crop dialog can
 * re-open non-destructively against the untouched source image instead of
@@ -4988,14 +5301,14 @@ z.object({
 	page: 1,
 	pageSize: 50
 });
-z.object({
+const listChangeRequestsPageResponseSchema = z.object({
 	changeRequests: z.array(changeRequestSchema),
 	total: z.number().int().nonnegative(),
 	totalPages: z.number().int().nonnegative(),
 	page: z.number().int().min(1),
 	pageSize: z.number().int().min(1).max(100)
 });
-z.object({
+const changeRequestCountsSchema = z.object({
 	review: z.number().int().nonnegative(),
 	changes: z.number().int().nonnegative(),
 	created: z.number().int().nonnegative(),
@@ -5003,6 +5316,7 @@ z.object({
 	merged: z.number().int().nonnegative(),
 	rejected: z.number().int().nonnegative()
 });
+listChangeRequestsPageResponseSchema.extend({ counts: changeRequestCountsSchema });
 const SEARCH_SOURCES = [
 	"records",
 	"files",
@@ -5681,8 +5995,75 @@ const reportUnresolvableDocAssets = (slug, body, carried = /* @__PURE__ */ new S
 	if (unresolved.length === 0) return void 0;
 	return `Doc "${slug}" embeds ${unresolved.length} image(s) that this package does not carry (${unresolved.join(", ")}). Everything else about the doc is intact, but those images will not render on another host. Re-upload them in the Doc editor, or check that the source host can still serve them.`;
 };
+//#endregion
+//#region ../../packages/busabase-package/src/record-dependencies.ts
+const recordIdentity = (baseSlug, recordKey) => `${baseSlug}\u0000${recordKey}`;
+const toRecordKeyArray = (value) => {
+	if (Array.isArray(value)) return value.filter((item) => typeof item === "string" && item.length > 0);
+	if (typeof value === "string" && value.length > 0) return [value];
+	return [];
+};
+const collectBases = (nodes) => {
+	const bases = [];
+	for (const node of nodes) {
+		if (node.type === "base") bases.push(node);
+		if (node.type === "folder") bases.push(...collectBases(node.children));
+	}
+	return bases;
+};
+const label = (baseSlug, recordKey) => `${baseSlug}/${recordKey}`;
+/**
+* Order sample records so every required relation points at an already-created row.
+*
+* Optional relations remain a separate linking pass. Required relations cannot: the
+* Base rejects a record before that later pass if its required value is absent.
+*/
+const buildRecordCreateLayers = (nodes) => {
+	const bases = collectBases(nodes);
+	const basesBySlug = new Map(bases.map((base) => [base.slug, base]));
+	const records = /* @__PURE__ */ new Map();
+	for (const base of bases) for (const record of base.records) records.set(recordIdentity(base.slug, record.key), {
+		base,
+		record
+	});
+	const dependencies = /* @__PURE__ */ new Map();
+	for (const planned of records.values()) {
+		const id = recordIdentity(planned.base.slug, planned.record.key);
+		const required = /* @__PURE__ */ new Set();
+		for (const field of planned.base.base.fields) {
+			if (field.type !== "relation" || !field.required) continue;
+			const targetBaseSlug = field.options.targetBaseSlug;
+			if (!targetBaseSlug || !basesBySlug.has(targetBaseSlug)) throw new Error(`Required relation "${planned.base.slug}.${field.slug}" targets missing Base "${targetBaseSlug || "(unset)"}". Nothing was installed.`);
+			const keys = toRecordKeyArray(planned.record.fields[field.slug]);
+			if (keys.length === 0) throw new Error(`Sample record "${label(planned.base.slug, planned.record.key)}" is missing required relation "${field.slug}". Nothing was installed.`);
+			for (const key of keys) {
+				const dependency = recordIdentity(targetBaseSlug, key);
+				if (!records.has(dependency)) throw new Error(`Sample record "${label(planned.base.slug, planned.record.key)}" requires "${targetBaseSlug}/${key}" through relation "${field.slug}", but that target is not in this package. Nothing was installed.`);
+				required.add(dependency);
+			}
+		}
+		dependencies.set(id, required);
+	}
+	const remaining = new Map(records);
+	const created = /* @__PURE__ */ new Set();
+	const layers = [];
+	while (remaining.size > 0) {
+		const ready = [...remaining.entries()].filter(([id]) => [...dependencies.get(id) ?? []].every((dependency) => created.has(dependency))).sort(([, a], [, b]) => `${a.base.slug}\u0000${a.record.key}`.localeCompare(`${b.base.slug}\u0000${b.record.key}`, "en"));
+		if (ready.length === 0) {
+			const cycle = [...remaining.values()].map((item) => label(item.base.slug, item.record.key)).sort((a, b) => a.localeCompare(b, "en"));
+			throw new Error(`Required sample relations contain a cycle involving: ${cycle.join(", ")}. Required relation targets must be creatable first. Nothing was installed.`);
+		}
+		layers.push(ready.map(([, planned]) => planned));
+		for (const [id] of ready) {
+			remaining.delete(id);
+			created.add(id);
+		}
+	}
+	return layers;
+};
 const fieldKey = (baseSlug, fieldSlug) => `${baseSlug}\u0000${fieldSlug}`;
 const applyInstall = async (client, plan, options) => {
+	const recordCreateLayers = buildRecordCreateLayers(plan.tree.nodes);
 	const state = {
 		targetFolderNodeId: "",
 		created: {
@@ -5701,90 +6082,144 @@ const applyInstall = async (client, plan, options) => {
 	const bases = [];
 	const progress = options.onProgress ?? (() => {});
 	const app = resolveAppContext(plan, options);
-	const docAssetIds = await uploadDocAssets(client, plan.tree.assets ?? [], state, progress, options.serverUrl);
-	progress("Pass 1/5: creating the node tree…");
-	if (plan.existingTargetFolderNodeId) state.targetFolderNodeId = plan.existingTargetFolderNodeId;
-	else {
-		state.targetFolderNodeId = await createFolderNode(client, {
-			parentNodeId: void 0,
-			slug: plan.targetFolderSlug,
-			name: plan.tree.manifest.name,
-			description: plan.tree.manifest.description,
-			submittedBy: options.submittedBy,
-			metadata: app?.rootMetadata
-		});
-		state.created.folders++;
-	}
-	await createStructure(client, plan.tree.nodes, state.targetFolderNodeId, options, state, bases, fieldIds, docAssetIds, app);
-	if (app?.rootSkill) {
-		progress("Pass 1/5: installing the app skill…");
-		await createFileTreeNode(client, {
-			type: "skill",
-			slug: app.rootSkill.slug,
-			name: app.rootSkill.name,
-			description: app.rootSkill.description,
-			position: void 0,
-			files: app.rootSkill.files
-		}, state.targetFolderNodeId, options, state, app, { [TEMPLATE_SKILL_METADATA_KEY]: true });
-	}
-	const deferred = bases.filter((base) => base.node.base.fields.some(isDeferredField));
-	if (deferred.length > 0) {
-		progress("Pass 2/5: adding relation and AI fields…");
-		for (const base of deferred) for (const field of base.node.base.fields.filter(isDeferredField)) {
-			const updated = await client.bases.createField({
-				baseId: base.baseId,
-				slug: field.slug,
-				name: field.name,
-				type: field.type,
-				required: field.required,
-				options: toApiFieldOptions(field.options)
-			});
-			indexFields(fieldIds, base.node.slug, updated.fields);
-		}
-	}
-	const patchable = bases.flatMap((base) => base.node.base.fields.filter(needsFieldIdPatch).map((field) => ({
-		base,
-		field
-	})));
-	if (patchable.length > 0) {
-		progress("Pass 3/5: resolving inverse and AI source field references…");
-		for (const { base, field } of patchable) {
-			const fieldId = fieldIds.get(fieldKey(base.node.slug, field.slug));
-			if (!fieldId) throw new Error(`Internal error: no field id for ${base.node.slug}.${field.slug} in pass 3.`);
-			const patched = resolveFieldIdOptions(field, base.node.slug, fieldIds, state.warnings);
-			if (!patched) continue;
-			const changeRequest = await client.bases.fieldChangeRequest({
-				operation: "update",
-				baseId: base.baseId,
-				fieldId,
-				patch: { options: patched },
-				message: `Wire up ${base.node.slug}.${field.slug} references`,
+	let phase = "Pass 1/5 (structure)";
+	try {
+		const docAssetIds = await uploadDocAssets(client, plan.tree.assets ?? [], state, progress, options.serverUrl);
+		progress("Pass 1/5: creating the node tree…");
+		if (plan.existingTargetFolderNodeId) state.targetFolderNodeId = plan.existingTargetFolderNodeId;
+		else {
+			state.targetFolderNodeId = await createFolderNode(client, {
+				parentNodeId: void 0,
+				slug: plan.targetFolderSlug,
+				name: plan.tree.manifest.name,
+				description: plan.tree.manifest.description,
 				submittedBy: options.submittedBy,
-				autoMerge: true
+				metadata: app?.rootMetadata
 			});
-			if (changeRequest.status !== "merged") throw new Error(`Field reference wiring for ${base.node.slug}.${field.slug} was requested immediately but came back "${changeRequest.status}"; install cannot leave a Base's relation fields unwired.`);
+			state.created.folders++;
 		}
-	}
-	const recordIdsByKey = /* @__PURE__ */ new Map();
-	const withRecords = bases.filter((base) => base.node.records.length > 0);
-	if (withRecords.length > 0) {
-		progress("Pass 4/5: creating records…");
-		for (const base of withRecords) await createRecords(client, base, plan, options, state, recordIdsByKey, app);
-	}
-	const relationFieldSlugs = /* @__PURE__ */ new Map();
-	for (const base of bases) {
-		const slugs = base.node.base.fields.filter((field) => field.type === "relation").map((field) => field.slug);
-		if (slugs.length > 0) relationFieldSlugs.set(base.node.slug, slugs);
-	}
-	if (relationFieldSlugs.size > 0) {
-		progress("Pass 5/5: linking relations…");
+		await createStructure(client, plan.tree.nodes, state.targetFolderNodeId, options, state, bases, fieldIds, docAssetIds, app);
+		if (app?.rootSkill) {
+			progress("Pass 1/5: installing the app skill…");
+			await createFileTreeNode(client, {
+				type: "skill",
+				slug: app.rootSkill.slug,
+				name: app.rootSkill.name,
+				description: app.rootSkill.description,
+				position: void 0,
+				files: app.rootSkill.files
+			}, state.targetFolderNodeId, options, state, app, { [TEMPLATE_SKILL_METADATA_KEY]: true });
+		}
+		phase = "Pass 2/5 (relation and AI fields)";
+		const deferred = bases.filter((base) => base.node.base.fields.some(isDeferredField));
+		if (deferred.length > 0) {
+			progress("Pass 2/5: adding relation and AI fields…");
+			for (const base of deferred) for (const field of base.node.base.fields.filter(isDeferredField)) {
+				const updated = await client.bases.createField({
+					baseId: base.baseId,
+					slug: field.slug,
+					name: field.name,
+					type: field.type,
+					required: field.required,
+					options: toApiFieldOptions(field.options)
+				});
+				indexFields(fieldIds, base.node.slug, updated.fields);
+			}
+		}
+		phase = "Pass 3/5 (field reference wiring)";
+		const patchable = bases.flatMap((base) => base.node.base.fields.filter(needsFieldIdPatch).map((field) => ({
+			base,
+			field
+		})));
+		if (patchable.length > 0) {
+			progress("Pass 3/5: resolving inverse and AI source field references…");
+			for (const { base, field } of patchable) {
+				const fieldId = fieldIds.get(fieldKey(base.node.slug, field.slug));
+				if (!fieldId) throw new Error(`Internal error: no field id for ${base.node.slug}.${field.slug} in pass 3.`);
+				const patched = resolveFieldIdOptions(field, base.node.slug, fieldIds, state.warnings);
+				if (!patched) continue;
+				const changeRequest = await client.bases.fieldChangeRequest({
+					operation: "update",
+					baseId: base.baseId,
+					fieldId,
+					patch: { options: patched },
+					message: `Wire up ${base.node.slug}.${field.slug} references`,
+					submittedBy: options.submittedBy,
+					autoMerge: true
+				});
+				if (changeRequest.status !== "merged") throw new Error(`Field reference wiring for ${base.node.slug}.${field.slug} was requested immediately but came back "${changeRequest.status}"; install cannot leave a Base's relation fields unwired.`);
+			}
+		}
+		phase = "Pass 4/5 (sample records)";
+		const recordIdsByKey = /* @__PURE__ */ new Map();
+		if (recordCreateLayers.length > 0) {
+			progress("Pass 4/5: creating records…");
+			const basesBySlug = new Map(bases.map((base) => [base.node.slug, base]));
+			for (const layer of recordCreateLayers) {
+				const byBase = /* @__PURE__ */ new Map();
+				for (const planned of layer) {
+					const group = byBase.get(planned.base.slug) ?? [];
+					group.push(planned);
+					byBase.set(planned.base.slug, group);
+				}
+				for (const [baseSlug, planned] of [...byBase].sort(([a], [b]) => a.localeCompare(b, "en"))) {
+					const base = basesBySlug.get(baseSlug);
+					if (!base) throw new Error(`Internal error: no materialized Base for ${baseSlug} in pass 4.`);
+					await createRecords(client, base, planned.map((item) => item.record), plan, options, state, recordIdsByKey, app);
+				}
+			}
+		}
+		phase = "Pass 5/5 (relation links)";
+		const relationFields = /* @__PURE__ */ new Map();
 		for (const base of bases) {
-			const slugs = relationFieldSlugs.get(base.node.slug);
-			if (!slugs) continue;
-			await linkRelations(client, base, slugs, recordIdsByKey, options, state);
+			const fields = base.node.base.fields.filter((field) => field.type === "relation");
+			if (fields.length > 0) relationFields.set(base.node.slug, fields);
 		}
+		if (relationFields.size > 0) {
+			progress("Pass 5/5: linking relations…");
+			for (const base of bases) {
+				const fields = relationFields.get(base.node.slug);
+				if (!fields) continue;
+				await linkRelations(client, base, fields, recordIdsByKey, options, state);
+			}
+		}
+		return state;
+	} catch (error) {
+		const created = Object.entries(state.created).filter(([, count]) => count > 0).map(([kind, count]) => `${count} ${kind}`).join(", ");
+		const partial = created ? `Created before failure: ${created}. Target folder: ${plan.targetFolderSlug}.` : "No package resources were created.";
+		const pending = state.pendingChangeRequests ? ` ${state.pendingChangeRequests} ChangeRequest(s) may still be pending.` : "";
+		const reason = error instanceof Error ? error.message : String(error);
+		const message = `Install stopped during ${phase}. ${partial}${pending} Cause: ${reason}`;
+		const details = {
+			phase,
+			targetFolderSlug: plan.targetFolderSlug,
+			created: { ...state.created },
+			pendingChangeRequests: state.pendingChangeRequests
+		};
+		if (error instanceof Error) {
+			error.message = message;
+			throw attachInstallFailureDetails(error, details);
+		}
+		throw attachInstallFailureDetails(new Error(message), details);
 	}
-	return state;
+};
+/**
+* A property rather than a subclass: the whole point of the rethrow above is to
+* keep the original error's prototype (an `ORPCError`'s `code`/`status`/`data`
+* are what make a permission or quota failure actionable), so the diagnostics
+* have to ride along on it instead of replacing it.
+*/
+const INSTALL_FAILURE_DETAILS_KEY = "busabaseInstallFailure";
+const attachInstallFailureDetails = (error, details) => {
+	try {
+		Object.defineProperty(error, INSTALL_FAILURE_DETAILS_KEY, {
+			value: details,
+			enumerable: false,
+			configurable: true,
+			writable: true
+		});
+	} catch {}
+	return error;
 };
 const resolveAppContext = (plan, options) => {
 	if (!plan.isTemplate) return void 0;
@@ -6140,28 +6575,39 @@ const resolveFieldIdOptions = (field, baseSlug, fieldIds, warnings) => {
 const indexFields = (fieldIds, baseSlug, fields) => {
 	for (const field of fields) fieldIds.set(fieldKey(baseSlug, field.slug), field.id);
 };
-/** Values the server computes, and relation values (pass 5), are never sent in pass 4. */
-const toCreatableFields = (node, fields) => {
-	const typeBySlug = new Map(node.base.fields.map((field) => [field.slug, field.type]));
+/**
+* Values the server computes and optional relations are omitted in pass 4.
+* Required relations are resolved to canonical ids once their dependency layer exists.
+*/
+const toCreatableFields = (node, fields, recordIdsByKey) => {
+	const fieldBySlug = new Map(node.base.fields.map((field) => [field.slug, field]));
 	const result = {};
 	for (const [slug, value] of Object.entries(fields)) {
-		const type = typeBySlug.get(slug);
-		if (!type) continue;
-		if (type === "relation") continue;
-		if (PACKAGE_COMPUTED_FIELD_TYPES.includes(type)) continue;
-		if (type === "attachment") continue;
+		const field = fieldBySlug.get(slug);
+		if (!field) continue;
+		if (field.type === "relation") {
+			if (!field.required) continue;
+			const targetBaseSlug = field.options.targetBaseSlug;
+			const keys = toRecordKeyArray(value);
+			const targetIds = keys.map((key) => targetBaseSlug ? recordIdsByKey.get(recordIdentity(targetBaseSlug, key)) : void 0).filter((id) => Boolean(id));
+			if (targetIds.length !== keys.length) throw new Error(`Internal error: required relation ${node.slug}.${slug} was scheduled before its targets existed.`);
+			result[slug] = targetIds;
+			continue;
+		}
+		if (PACKAGE_COMPUTED_FIELD_TYPES.includes(field.type)) continue;
+		if (field.type === "attachment") continue;
 		result[slug] = value;
 	}
 	return result;
 };
-const createRecords = async (client, base, plan, options, state, recordIdsByKey, app) => {
+const createRecords = async (client, base, recordsToCreate, plan, options, state, recordIdsByKey, app) => {
 	const mergeRecords = options.autoMerge || (app?.mergeSampleRecords ?? false);
-	const records = [...base.node.records].sort((a, b) => a.key.localeCompare(b.key, "en"));
+	const records = [...recordsToCreate].sort((a, b) => a.key.localeCompare(b.key, "en"));
 	for (let offset = 0; offset < records.length; offset += 200) {
 		const batch = records.slice(offset, offset + 200);
 		const changeRequest = await client.bases.createBulkChangeRequest({
 			baseId: base.baseId,
-			records: batch.map((record) => toCreatableFields(base.node, record.fields)),
+			records: batch.map((record) => toCreatableFields(base.node, record.fields, recordIdsByKey)),
 			message: `Install ${batch.length} record(s) into ${base.node.slug}`,
 			submittedBy: options.submittedBy,
 			idempotencyKey: batchIdempotencyKey(plan.tree.manifest.name, batch[0].key),
@@ -6174,7 +6620,7 @@ const createRecords = async (client, base, plan, options, state, recordIdsByKey,
 		const created = (await approveAndMerge(client, changeRequest.id)).changeRequest.operations.filter((operation) => operation.operation === "record_create").sort((a, b) => a.position - b.position);
 		for (const [index, record] of batch.entries()) {
 			const recordId = created[index]?.mergedRecordId;
-			if (recordId) recordIdsByKey.set(record.key, recordId);
+			if (recordId) recordIdsByKey.set(recordIdentity(base.node.slug, record.key), recordId);
 		}
 		state.created.records += batch.length;
 	}
@@ -6189,30 +6635,31 @@ const createRecords = async (client, base, plan, options, state, recordIdsByKey,
 * so the same package always produces the same batches and therefore the same keys.
 */
 const batchIdempotencyKey = (packageName, firstRecordKey) => `pkg:${packageName}:${firstRecordKey}`;
-const linkRelations = async (client, base, relationFieldSlugs, recordIdsByKey, options, state) => {
+const linkRelations = async (client, base, relationFields, recordIdsByKey, options, state) => {
 	for (const record of base.node.records) {
 		const relationValues = {};
-		let hasRelation = false;
-		for (const slug of relationFieldSlugs) {
-			const value = record.fields[slug];
-			const keys = toKeyArray(value);
+		let needsUpdate = false;
+		for (const field of relationFields) {
+			const value = record.fields[field.slug];
+			const keys = toRecordKeyArray(value);
 			if (keys.length === 0) continue;
-			const targetIds = keys.map((key) => recordIdsByKey.get(key)).filter((id) => Boolean(id));
-			const unresolved = keys.filter((key) => !recordIdsByKey.has(key));
-			if (unresolved.length > 0) state.warnings.push(`Record "${record.key}" in base "${base.node.slug}" links field "${slug}" to ${unresolved.length} record(s) that are not in this package — those links were skipped.`);
+			const targetBaseSlug = field.options.targetBaseSlug;
+			const targetIds = keys.map((key) => targetBaseSlug ? recordIdsByKey.get(recordIdentity(targetBaseSlug, key)) : void 0).filter((id) => Boolean(id));
+			const unresolved = keys.filter((key) => !targetBaseSlug || !recordIdsByKey.has(recordIdentity(targetBaseSlug, key)));
+			if (unresolved.length > 0) state.warnings.push(`Record "${record.key}" in base "${base.node.slug}" links field "${field.slug}" to ${unresolved.length} record(s) that are not in target Base "${targetBaseSlug || "(unset)"}" — those links were skipped.`);
 			if (targetIds.length > 0) {
-				relationValues[slug] = targetIds;
-				hasRelation = true;
+				relationValues[field.slug] = targetIds;
+				if (!field.required) needsUpdate = true;
 			}
 		}
-		if (!hasRelation) continue;
-		const recordId = recordIdsByKey.get(record.key);
+		if (!needsUpdate) continue;
+		const recordId = recordIdsByKey.get(recordIdentity(base.node.slug, record.key));
 		if (!recordId) continue;
 		const changeRequest = await client.records.changeRequest({
 			operation: "update",
 			recordId,
 			fields: {
-				...toCreatableFields(base.node, record.fields),
+				...toCreatableFields(base.node, record.fields, recordIdsByKey),
 				...relationValues
 			},
 			message: `Link relations for ${base.node.slug}`,
@@ -6223,11 +6670,6 @@ const linkRelations = async (client, base, relationFieldSlugs, recordIdsByKey, o
 		await approveAndMerge(client, changeRequest.id);
 	}
 };
-const toKeyArray = (value) => {
-	if (Array.isArray(value)) return value.filter((item) => typeof item === "string" && item.length > 0);
-	if (typeof value === "string" && value.length > 0) return [value];
-	return [];
-};
 /** Merging requires an `approved` status, so every auto-merge is review-then-merge. */
 const approveAndMerge = async (client, changeRequestId) => {
 	const reviewResult = (await client.changeRequests.review({
@@ -7368,6 +7810,7 @@ const buildInstallPlan = (tree, target, options = {}) => {
 		planned = applyRenames(prefixed, collisions, target.existingNodeSlugsByType);
 		for (const [installedSlug, originalSlug] of collectSlugRewrites(tree, planned)) resourceKeysBySlug[installedSlug] = originalSlug;
 	}
+	buildRecordCreateLayers(planned.nodes);
 	collectWarnings(planned, warnings);
 	const counts = countTree(planned);
 	if (counts.files > 5e3) throw new Error(`Package has ${counts.files} files, above the ${PACKAGE_MAX_FILE_COUNT}-file limit. Nothing was installed.`);
@@ -8495,6 +8938,151 @@ const readDirectoryFiles = async (dir) => {
 	return files;
 };
 //#endregion
+//#region src/paginate.ts
+/**
+* `--all`: follow the cursor to the end instead of making the caller loop.
+*
+* Every listing in this CLI is bounded — that is the point of the `limit` work —
+* but "bounded" moves the burden onto the caller, who now has to notice
+* `nextCursor`, thread it back in, and know when to stop. An agent that misses
+* that reports a truncated answer as the whole answer, which is the failure the
+* `record_query` task guidance warns about in prose. This does it in code.
+*
+* Rows stream out as NDJSON — one JSON object per line — rather than
+* accumulating into one array, so memory stays flat and a consumer can start
+* work on page 1 while page 9 is still in flight. That is why `--all` overrides
+* `--output`: a 40,000-row table is not a thing anyone wanted.
+*/
+/**
+* Read a page out of whatever the command returned.
+*
+* Two protocols exist and both are honoured. Most paginated endpoints return
+* `{ rows, nextCursor }`. `GET /assets` returns a bare array and pages by the
+* last row's `id`, with a short page meaning the end — a shape chosen there to
+* keep the response backwards compatible for the web and mobile clients.
+*/
+function readPage(result, limit) {
+	const envelope = asEnvelope(result);
+	if (envelope) {
+		const cursor = envelope.meta.find(([key]) => key === "nextCursor")?.[1];
+		if (cursor === void 0) return void 0;
+		return {
+			rows: envelope.rows,
+			nextCursor: typeof cursor === "string" ? cursor : null
+		};
+	}
+	if (!Array.isArray(result)) return void 0;
+	if (limit === void 0 || result.length < limit) return {
+		rows: result,
+		nextCursor: null
+	};
+	const id = result[result.length - 1]?.id;
+	return {
+		rows: result,
+		nextCursor: typeof id === "string" ? id : null
+	};
+}
+/** Stops a broken server or a cursor that never advances from looping forever. */
+const MAX_PAGES = 1e4;
+/**
+* Stream every page as NDJSON. Returns the number of rows written.
+*
+* A cap that truncates is always announced on stderr: a silently short answer
+* that looks complete is the exact failure this is meant to prevent.
+*/
+async function paginateAll(options) {
+	const { fetchPage, limit, maxItems, write, notify } = options;
+	let cursor;
+	let written = 0;
+	let seen = 0;
+	for (let pageIndex = 0; pageIndex < MAX_PAGES; pageIndex += 1) {
+		const result = await fetchPage(cursor);
+		const page = readPage(result, limit);
+		if (!page) {
+			write(JSON.stringify(result));
+			return 1;
+		}
+		seen += page.rows.length;
+		for (const row of page.rows) {
+			if (maxItems !== void 0 && written >= maxItems) {
+				notify(`[busabase-cli] --max-items ${maxItems} reached; stopped early with more rows available.`);
+				return written;
+			}
+			write(JSON.stringify(row));
+			written += 1;
+		}
+		if (!page.nextCursor) return written;
+		if (page.nextCursor === cursor) {
+			notify("[busabase-cli] the server returned the same cursor twice; stopping to avoid a loop.");
+			return written;
+		}
+		cursor = page.nextCursor;
+	}
+	notify(`[busabase-cli] stopped after ${MAX_PAGES} pages (${seen} rows scanned).`);
+	return written;
+}
+//#endregion
+//#region src/retry.ts
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 2e4;
+const READ_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const isNetworkError = (error) => error instanceof TypeError || /fetch failed|econnreset|econnrefused|etimedout|socket hang up/i.test(error instanceof Error ? error.message : String(error));
+/** `Retry-After` is either delay-seconds or an HTTP-date; both are legal. */
+function parseRetryAfter(header, now = Date.now()) {
+	if (!header) return void 0;
+	const seconds = Number(header.trim());
+	if (Number.isFinite(seconds) && seconds >= 0) return Math.min(seconds * 1e3, MAX_DELAY_MS);
+	const at = Date.parse(header);
+	if (Number.isNaN(at)) return void 0;
+	return Math.min(Math.max(at - now, 0), MAX_DELAY_MS);
+}
+/** Whether this outcome is worth another attempt for a request using `method`. */
+function shouldRetry(method, status) {
+	if (status === 429) return true;
+	if (!READ_METHODS.has(method.toUpperCase())) return false;
+	return status === void 0 || status >= 500;
+}
+/**
+* Wrap a fetch so transient failures are retried with exponential backoff.
+* Returns `base` unchanged when `retries` is 0, so the no-retry path adds no
+* wrapper and no behaviour.
+*/
+function withRetry(base, options) {
+	const { retries } = options;
+	if (retries <= 0) return base;
+	const sleep = options.sleep ?? defaultSleep;
+	const notify = options.notify ?? ((message) => console.error(message));
+	const jitter = options.jitter ?? Math.random;
+	return (async (input, init) => {
+		const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+		for (let attempt = 0;; attempt += 1) {
+			let response;
+			let failure;
+			try {
+				response = await base(input, init);
+			} catch (error) {
+				if (!isNetworkError(error)) throw error;
+				failure = error;
+			}
+			const status = response?.status;
+			const last = attempt >= retries;
+			if (!shouldRetry(method, status) || last) {
+				if (response) return response;
+				throw failure;
+			}
+			const backoff = Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+			const delay = parseRetryAfter(response?.headers.get("retry-after") ?? null) ?? Math.round(backoff * (.5 + jitter() * .5));
+			notify(`[busabase-cli] ${status ? `HTTP ${status}` : "connection failed"} — retrying in ${Math.round(delay / 1e3)}s (attempt ${attempt + 2} of ${retries + 1})`);
+			await sleep(delay);
+		}
+	});
+}
+//#endregion
 //#region src/task-command.ts
 const collect = (value, previous = []) => [...previous, value];
 /** Range-checks before the request goes out, so a cap surfaces as a usage error. */
@@ -8533,10 +9121,13 @@ const applyParam = (cmd, param) => {
 		case "stringArray":
 			cmd.option(`${flag} <value>`, `${description} (repeatable)`, collect);
 			return;
-		case "json":
-			cmd.option(`${jsonFlagFor(param)} <json|@file>`, description);
+		case "json": {
+			const jsonOption = `${jsonFlagFor(param)} <json|@file>`;
+			if (param.required) cmd.requiredOption(jsonOption, description);
+			else cmd.option(jsonOption, description);
 			if (param.cliShorthand) cmd.option(`${param.cliShorthand.flag} ${param.cliShorthand.placeholder}`, param.cliShorthand.description, collect);
 			return;
+		}
 		default: if (param.required) cmd.requiredOption(`${flag} <value>`, description);
 		else cmd.option(`${flag} <value>`, description);
 	}
@@ -8586,6 +9177,7 @@ const registerOne = (program, task, deps, path, preset = {}, summaryOverride) =>
 		}
 		applyParam(cmd, param);
 	}
+	if (task.guidance) cmd.addHelpText("after", `\n${wrapGuidance(rewriteTaskNames(task.guidance))}`);
 	if (task.examples && task.examples.length > 0 && Object.keys(preset).length === 0) cmd.addHelpText("after", `\nExamples:\n  ${task.examples.join("\n  ")}`);
 	cmd.action(deps.runAction(async (client, opts) => task.execute(client, {
 		...buildInput(task, opts, deps),
@@ -8593,11 +9185,108 @@ const registerOne = (program, task, deps, path, preset = {}, summaryOverride) =>
 	})));
 };
 const registerTaskCommands = (program, tasks, deps) => {
+	for (const task of tasks) cliPathByTaskName.set(task.name, `busabase-cli ${task.cliPath.join(" ")}`);
 	for (const task of tasks) {
 		registerOne(program, task, deps, task.cliPath);
 		for (const variant of task.cliVariants ?? []) registerOne(program, task, deps, variant.path, variant.preset, variant.summary);
 	}
 };
+/**
+* Guidance is written once and read by two surfaces, so it names sibling tasks
+* by their MCP tool name (`record_find_by_field`). That is not something a CLI
+* caller can type — the command is `records by-field-text` — so the shared text
+* is rewritten to this surface's vocabulary rather than forked.
+*/
+const rewriteTaskNames = (text) => text.replace(/`([a-z][a-z0-9_]*)`/g, (match, name) => {
+	const path = cliPathByTaskName.get(name);
+	return path ? `\`${path}\`` : match;
+});
+/** Filled by {@link registerTaskCommands}; empty until the surface is built. */
+const cliPathByTaskName = /* @__PURE__ */ new Map();
+/** Reflow guidance to the width commander uses for the rest of the help screen. */
+const wrapGuidance = (text, width = 78) => {
+	const lines = [];
+	let line = "";
+	for (const word of text.split(/\s+/).filter(Boolean)) if (line && `${line} ${word}`.length > width) {
+		lines.push(line);
+		line = word;
+	} else line = line ? `${line} ${word}` : word;
+	if (line) lines.push(line);
+	return lines.join("\n");
+};
+//#endregion
+//#region src/wait.ts
+/**
+* `--wait`: block until a submitted proposal is actually decided.
+*
+* Review-first is the product's whole point, so the useful unit of work for a
+* caller is not "the change request was filed" — it is "the change request was
+* merged, or it wasn't". Without this every caller writes the same poll loop
+* against `change-requests get`, and an agent that skips it reports a proposal
+* nobody has looked at as a completed task.
+*/
+/** Statuses that will not change again on their own. */
+const TERMINAL = /* @__PURE__ */ new Set([
+	"merged",
+	"rejected",
+	"closed",
+	"abandoned"
+]);
+const isChangeRequest = (value) => {
+	if (!value || typeof value !== "object") return false;
+	const row = value;
+	return typeof row.id === "string" && row.id.startsWith("crq") && typeof row.status === "string";
+};
+/**
+* Find the change request a command's result is about.
+*
+* The shape differs across the surface — some routes return the change request
+* itself, some wrap it (`{ changeRequest }`), some return the materialized thing
+* with `materialized: false` alongside — so this looks for the id rather than
+* asking every command to declare it.
+*/
+function findChangeRequestId(result) {
+	if (isChangeRequest(result)) return result.id;
+	if (Array.isArray(result)) {
+		for (const item of result) {
+			const found = findChangeRequestId(item);
+			if (found) return found;
+		}
+		return;
+	}
+	if (!result || typeof result !== "object") return void 0;
+	const row = result;
+	if (typeof row.changeRequestId === "string") return row.changeRequestId;
+	for (const key of ["changeRequest", "changeRequests"]) {
+		const found = findChangeRequestId(row[key]);
+		if (found) return found;
+	}
+}
+const DEFAULT_POLL_MS = 3e3;
+/** Poll until the change request settles or the budget runs out. */
+async function waitForChangeRequest(options) {
+	const { changeRequestId, read, timeoutMs, pollMs = DEFAULT_POLL_MS, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now, notify = () => {} } = options;
+	const deadline = now() + timeoutMs;
+	let latest;
+	let status = "unknown";
+	for (;;) {
+		latest = await read(changeRequestId);
+		status = isChangeRequest(latest) ? latest.status : "unknown";
+		if (TERMINAL.has(status)) return {
+			kind: "settled",
+			status,
+			changeRequest: latest
+		};
+		const remaining = deadline - now();
+		if (remaining <= 0) return {
+			kind: "timeout",
+			status,
+			changeRequest: latest
+		};
+		notify(`[busabase-cli] ${changeRequestId} is ${status}; waiting for a reviewer (${Math.round(remaining / 1e3)}s left)`);
+		await sleep(Math.min(pollMs, remaining));
+	}
+}
 //#endregion
 //#region src/run.ts
 /** Public docs page covering every error below, for both Cloud and local. Linked from each error. */
@@ -8629,9 +9318,12 @@ function resolveConfig(opts) {
 		webUrl: process.env.BUSABASE_WEB_URL ?? file.BUSABASE_WEB_URL ?? baseUrl,
 		apiKey: opts.apiKey ?? process.env.BUSABASE_API_KEY ?? file.BUSABASE_API_KEY,
 		spaceId: opts.spaceId ?? process.env.BUSABASE_SPACE_ID ?? file.BUSABASE_SPACE_ID,
-		output: opts.output ?? configuredOutput() ?? "text"
+		output: opts.output ?? configuredOutput() ?? "text",
+		fetch: withRetry(fetch, { retries: opts.retries ?? DEFAULT_RETRIES })
 	};
 }
+/** Enough to ride out a rate limiter or a proxy blip; not enough to hide a real outage. */
+const DEFAULT_RETRIES = 2;
 /**
 * Config flags accepted anywhere on the line (`busabase-cli --output json bases list` and
 * `busabase-cli bases list --output json` both work): declared on the root program AND on every
@@ -8644,14 +9336,20 @@ const GLOBAL_LONG_FLAGS = /* @__PURE__ */ new Set([
 	"--space-id",
 	"--output",
 	"--profile",
-	"--config"
+	"--config",
+	"--slim",
+	"--retries",
+	"--all",
+	"--max-items",
+	"--wait",
+	"--wait-timeout"
 ]);
 function addGlobalFlags(cmd) {
 	return cmd.option("--base-url <url>", `server base URL (env BUSABASE_BASE_URL, default ${DEFAULT_BASE_URL})`).option("--api-key <token>", "bearer token for cloud hosts (env BUSABASE_API_KEY)").option("--space-id <id>", "target Busabase space (env BUSABASE_SPACE_ID)").option("--profile <name>", "account to use for this command (env BUSABASE_PROFILE)").option("--config <path>", "read credentials from this file instead (env BUSABASE_CONFIG)").addOption(new Option("--output <fmt>", "text | table | json (default text)").choices([
 		"text",
 		"table",
 		"json"
-	]));
+	])).option("--slim", "drop hydrated parents (a record's full `base`, `createdByUser`, `headCommit`) and keep their ids").option("--retries <n>", "extra attempts on 429 / 5xx / dropped connections (default 2, 0 disables)", parseNonNegativeInt).option("--all", "follow the cursor to the end and stream every row as NDJSON").option("--max-items <n>", "stop --all after this many rows", parsePositiveInt).option("--wait", "after submitting a Change Request, block until a reviewer merges or rejects it").option("--wait-timeout <seconds>", "budget for --wait (default 300)", parsePositiveInt);
 }
 const parseNum = (value) => {
 	const parsed = Number(value);
@@ -8663,6 +9361,11 @@ const parsePositiveInt = (value) => {
 	if (!Number.isInteger(parsed) || parsed < 1) throw new InvalidArgumentError("expected a positive integer");
 	return parsed;
 };
+const parseNonNegativeInt = (value) => {
+	const parsed = parseNum(value);
+	if (!Number.isInteger(parsed) || parsed < 0) throw new InvalidArgumentError("expected a non-negative integer");
+	return parsed;
+};
 const parseBoolean = (value) => {
 	if (value === "true") return true;
 	if (value === "false") return false;
@@ -8739,13 +9442,9 @@ function parseJsonValue(raw, flagName) {
 * better off than when the field was silently dropped.
 */
 function formatIssues(issues) {
-	if (!Array.isArray(issues) || issues.length === 0) return void 0;
-	return issues.map((issue) => {
-		if (!issue || typeof issue !== "object") return String(issue);
-		const { path, message } = issue;
-		const pathLabel = Array.isArray(path) && path.length > 0 ? path.join(".") : void 0;
-		return pathLabel ? `${pathLabel}: ${message}` : String(message ?? issue);
-	}).join("; ");
+	const parsed = toIssues(issues);
+	if (!parsed) return void 0;
+	return parsed.map(({ path, message }) => path ? `${path}: ${message}` : message).join("; ");
 }
 function formatRawErrorBody(status, statusText, text) {
 	try {
@@ -8760,7 +9459,7 @@ function formatRawErrorBody(status, statusText, text) {
 /** Raw fetch for endpoints outside the typed contract (health / openapi / api passthrough). */
 async function rawFetch(config, method, path, body) {
 	const url = `${normalizeBaseUrl(config.baseUrl)}${path}`;
-	const res = await fetch(url, {
+	const res = await (config.fetch ?? fetch)(url, {
 		method: method.toUpperCase(),
 		headers: {
 			...body !== void 0 ? { "content-type": "application/json" } : {},
@@ -8878,10 +9577,60 @@ function runAction(state, handler) {
 		if (refreshedToken) config.apiKey = refreshedToken;
 		state.config = config;
 		assertCredentialNotExpired(config.apiKey);
-		const result = await handler(createBusabaseClient(config), opts, config);
-		console.log(render(result, config.output));
+		const client = createBusabaseClient(config);
+		if (opts.all) {
+			await streamAllPages(client, opts, config, handler);
+			return;
+		}
+		const result = await handler(client, opts, config);
+		console.log(render(opts.slim ? slim(result) : result, config.output));
+		if (opts.wait) await awaitReview(client, opts, config, result);
 	};
 }
+/** Default `--wait` budget: long enough for a reviewer who is at their desk. */
+const DEFAULT_WAIT_SECONDS = 300;
+/**
+* Block until the Change Request this command just filed is decided.
+*
+* The result is printed first, so a caller that times out still has the id it
+* needs to come back to. Exit codes carry the outcome (see `errors.ts`): merged
+* is success, rejected is a decision the caller must branch on, and a timeout is
+* neither — nothing was decided, so the write must NOT be retried.
+*/
+async function awaitReview(client, opts, config, result) {
+	const changeRequestId = findChangeRequestId(result);
+	if (!changeRequestId) {
+		console.error("[busabase-cli] --wait: this command filed no Change Request; nothing to wait for.");
+		return;
+	}
+	const outcome = await waitForChangeRequest({
+		changeRequestId,
+		read: (id) => client.changeRequests.get({ changeRequestId: id }),
+		timeoutMs: (opts.waitTimeout ?? DEFAULT_WAIT_SECONDS) * 1e3,
+		notify: (message) => console.error(message)
+	});
+	console.log(render(opts.slim ? slim(outcome.changeRequest) : outcome.changeRequest, config.output));
+	if (outcome.kind === "timeout") throw new CliOutcomeError("TIMEOUT", `--wait timed out: ${changeRequestId} is still ${outcome.status}. Nothing was decided — do NOT resubmit; poll it with \`busabase-cli change-requests get --change-request-id ${changeRequestId}\`.`);
+	if (outcome.status !== "merged") throw new CliOutcomeError("REVIEW_REJECTED", `${changeRequestId} was ${outcome.status}, not merged.`);
+}
+/**
+* `--all` re-runs the same handler with a moving cursor. The handler reads its
+* input off `opts`, so advancing the page is a matter of setting `opts.cursor`
+* before each call rather than teaching every command a second code path.
+*/
+async function streamAllPages(client, opts, config, handler) {
+	if (await paginateAll({
+		fetchPage: async (cursor) => {
+			opts.cursor = cursor;
+			const result = await handler(client, opts, config);
+			return opts.slim ? slim(result) : result;
+		},
+		limit: typeof opts.limit === "number" ? opts.limit : void 0,
+		maxItems: typeof opts.maxItems === "number" ? opts.maxItems : void 0,
+		write: (line) => console.log(line),
+		notify: (message) => console.error(message)
+	}) === 0) console.error("[busabase-cli] no rows.");
+}
 /**
 * {@link runAction} for a command with one positional argument. Commander passes
 * `(arg, opts, cmd)` to such an action, so the arity differs from a flags-only leaf.
@@ -8895,7 +9644,7 @@ function runArgAction(state, handler) {
 		state.config = config;
 		assertCredentialNotExpired(config.apiKey);
 		const result = await handler(arg, createBusabaseClient(config), opts, config);
-		console.log(render(result, config.output));
+		console.log(render(opts.slim ? slim(result) : result, config.output));
 	};
 }
 /**
@@ -8912,7 +9661,7 @@ function runLocalArgAction(handler) {
 		const opts = cmd.optsWithGlobals();
 		const config = resolveConfig(opts);
 		const result = await handler(arg, opts, config);
-		console.log(render(result, config.output));
+		console.log(render(opts.slim ? slim(result) : result, config.output));
 	};
 }
 function pkgVersion() {
@@ -9045,11 +9794,33 @@ function unionVariants(inputSchema, discriminator = "operation") {
 	return variants;
 }
 /**
+* Words of an identifier, however it was spelled: `changeRequests` + `reviewMany`
+* and `change_requests_review_many` both reduce to
+* `change requests review many`. Lets the CLI compare its own generated command
+* paths against the MCP tool names in {@link TASK_SUPERSEDED_MCP_TOOLS} without
+* either side having to know how the other spells things.
+*/
+const identifierWords = (parts) => parts.flatMap((part) => part.split(/[_\-\s]+/)).flatMap((part) => part.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(" ")).filter(Boolean).map((word) => word.toLowerCase()).join(" ");
+/**
+* Endpoint commands a curated task command already covers.
+*
+* The MCP adapter has always dropped these so "a catalog carries one way to do
+* each job rather than two" — and then the CLI published BOTH spellings, which
+* is a third of a 30 KB help screen an agent reads to orient itself. Same list,
+* same reason, one more consumer.
+*
+* Hidden, never removed: every one of them still runs, so no existing script
+* breaks, and `--help-all` prints them.
+*/
+const SUPERSEDED_COMMAND_PATHS = new Set(TASK_SUPERSEDED_MCP_TOOLS.map((tool) => identifierWords([tool])));
+/**
 * Procedures a curated command already exposes under a DIFFERENT name (so the
 * name-collision guard wouldn't catch them). Keyed `group.procKey`.
 */
 const GENERATED_SKIP = /* @__PURE__ */ new Set([
 	"search",
+	"guides.list",
+	"guides.read",
 	"auth.verify",
 	"records.search",
 	"records.listChangeRequests",
@@ -9079,7 +9850,8 @@ function registerGeneratedCommands(program, state) {
 	const addOneLeaf = (parent, navPath, procKey, proc, name, fields, description) => {
 		const { route } = proc["~orpc"];
 		if (parent.commands.some((c) => c.name() === name || c.aliases().includes(name))) return;
-		const leaf = parent.command(name).description(description ?? route.summary ?? `${route.method} ${route.path}`);
+		const superseded = SUPERSEDED_COMMAND_PATHS.has(identifierWords([parent.name(), name]));
+		const leaf = parent.command(name, superseded ? { hidden: true } : void 0).description(description ?? route.summary ?? `${route.method} ${route.path}`);
 		for (const f of fields) {
 			if (f.pinned !== void 0) continue;
 			const flag = `--${kebab(f.key)}`;
@@ -9154,14 +9926,26 @@ function flagSignature(cmd) {
 	}
 	return parts.join(" ");
 }
-const isHelpHidden = (cmd) => Boolean(cmd._noHelp);
+/**
+* Commander records `command(name, { hidden })` and `{ noHelp }` on `_hidden`;
+* this read `_noHelp`, which commander never sets, so it always answered false
+* and nothing was ever actually hidden from the root help.
+*/
+const isHelpHidden = (cmd) => Boolean(cmd._hidden) || Boolean(cmd._noHelp);
+/**
+* Set for the duration of a `--help-all` render. A module-level flag rather than
+* a parameter because commander calls the help hook itself, with no way to
+* thread an argument through.
+*/
+let showAllCommands = false;
 /**
 * Root help "Commands:" section: every leaf with its full flag signature (the flat
 * commander listing would only show group names). Generated from the command tree,
 * never hand-written.
 */
-function commandsSection(program) {
+function commandsSection(program, showAll = false) {
 	const lines = ["Commands:"];
+	const skip = (cmd) => cmd.name() === "help" || !showAll && isHelpHidden(cmd);
 	const entry = (prefix, cmd) => {
 		const sig = [prefix, flagSignature(cmd)].filter(Boolean).join(" ");
 		const desc = cmd.description();
@@ -9170,12 +9954,12 @@ function commandsSection(program) {
 		return `  ${sig}\n${" ".repeat(44)}${desc}`;
 	};
 	for (const cmd of program.commands) {
-		if (cmd.name() === "help" || isHelpHidden(cmd)) continue;
-		const leaves = cmd.commands.filter((leaf) => leaf.name() !== "help" && !isHelpHidden(leaf));
+		if (skip(cmd)) continue;
+		const leaves = cmd.commands.filter((leaf) => !skip(leaf));
 		if (leaves.length > 0) {
 			lines.push("");
 			for (const leaf of leaves) lines.push(entry(`${cmd.name()} ${leaf.name()}`, leaf));
-		} else lines.push(entry(cmd.name(), cmd));
+		} else if (cmd.commands.length === 0) lines.push(entry(cmd.name(), cmd));
 	}
 	return lines.join("\n");
 }
@@ -9187,7 +9971,12 @@ Several accounts: \`login --profile <name>\` adds one, \`auth status\` lists the
 \`auth switch\` changes which is active. Several spaces on one account (the norm on
 Cloud): \`space list\` / \`space use\`.
 
+New here? \`busabase-cli guide\` is the operating manual — read \`workspace\` before
+proposing changes. Endpoint commands a task command already covers are hidden;
+\`--help-all\` prints them (they all still run).
+
 Docs: https://busabase.com/docs · Troubleshooting: ${DOCS_TROUBLESHOOTING}`;
+/** Exported for the help-example test, which walks the command tree in-process. */
 function buildProgram(state = {}) {
 	const program = new Command("busabase-cli");
 	program.description("Client for the Busabase OpenAPI REST API — talks to `busabase server` or Cloud.").usage("[global flags] <command> [flags]").version(pkgVersion(), "-v, --version", "print busabase-cli version").exitOverride().showHelpAfterError("(run `busabase-cli --help` for the full command list)").addHelpText("beforeAll", () => banner(resolveConfig(program.opts()).baseUrl));
@@ -9195,6 +9984,29 @@ function buildProgram(state = {}) {
 	addGlobalFlags(program.command("health")).description("Server health check (GET /api/health)").action(runAction(state, (_client, _opts, config) => rawFetch(config, "GET", "/api/health")));
 	addGlobalFlags(program.command("openapi")).description("Fetch the OpenAPI document").action(runAction(state, (_client, _opts, config) => rawFetch(config, "GET", "/api/v1/openapi.json")));
 	addGlobalFlags(program.command("whoami")).description("Active space, user, and membership").action(runAction(state, (client) => client.auth.verify()));
+	addGlobalFlags(program.command("guide")).argument("[topic]", "which guide to read; omit to list the topics this server serves").description("Read the Busabase operating manual (approval-first rules, AirApp contract)").addHelpText("after", `
+Read this BEFORE unfamiliar work. It carries the conventions this workspace
+expects, which no flag or schema can express on its own.
+
+Examples:
+  busabase-cli guide                 # what is available here
+  busabase-cli guide workspace       # the approval-first workflow
+  busabase-cli guide airapp          # REQUIRED before writing any AirApp file`).action(async (topic, _opts, cmd) => {
+		const config = resolveConfig(cmd.optsWithGlobals());
+		state.config = config;
+		const client = createBusabaseClient(config);
+		if (!topic) {
+			console.log(render(await client.guides.list(), config.output));
+			return;
+		}
+		const guide = await client.guides.read({ topic });
+		if (config.output === "json") {
+			console.log(render(guide, config.output));
+			return;
+		}
+		console.log(guide.content);
+		console.error(`\n[busabase-cli] other topics: ${guide.otherTopics.join(", ") || "(none)"}`);
+	});
 	addGlobalFlags(program.command("login")).description("Connect the CLI to Busabase — Personal/local, Cloud, or self-hosted").option("--device-code", "force device authorization and skip the method prompt").option("--oauth", "legacy same-machine OAuth callback flow").option("--no-browser", "print the sign-in URL instead of opening a browser").option("--refresh", "rotate the saved OAuth token set (no browser, no re-login)").addHelpText("after", `
 Busabase is an approval-first database and knowledge base for AI agents: agents
 propose changes, humans review and merge what becomes trusted data.
@@ -9614,7 +10426,7 @@ To add content to a space that is already in use, use \`busabase-cli install\` i
 			leaf.usage(`${sig ? `${sig} ` : ""}[global flags]`);
 		}
 	}
-	program.addHelpText("after", () => `\n${commandsSection(program)}\n${HELP_FOOTER}`);
+	program.addHelpText("after", () => `\n${commandsSection(program, showAllCommands)}\n${HELP_FOOTER}`);
 	program.configureHelp({ visibleCommands: () => [] });
 	return program;
 }
@@ -9629,17 +10441,48 @@ async function runCli(argv) {
 		program.outputHelp();
 		return 0;
 	}
+	if (argv.includes("--help-all")) {
+		console.log(renderedHelp({ showAll: true }));
+		return 0;
+	}
 	try {
 		await program.parseAsync(argv, { from: "user" });
 		return 0;
 	} catch (error) {
-		if (error instanceof CommanderError) return error.exitCode === 0 ? 0 : 1;
+		const json = errorOutputIsJson(state, argv);
+		if (error instanceof CommanderError) {
+			if (error.exitCode === 0) return 0;
+			if (json) console.log(JSON.stringify({
+				ok: false,
+				code: "USAGE",
+				message: error.message,
+				retryable: false
+			}, null, 2));
+			return EXIT_CODES.USAGE;
+		}
+		const classified = classifyError(error);
+		if (json) console.log(JSON.stringify(errorEnvelope(classified), null, 2));
 		console.error(explainError(error, state.config ?? resolveConfig({})));
-		return 1;
+		return classified.exitCode;
 	}
 }
-function renderedHelp() {
+/**
+* Whether a failed run should print the machine-readable envelope.
+*
+* `state.config` is set by the first command that resolves one, but a failure
+* can happen before that (an unknown option, a bad `--config` path), so the raw
+* argv is the fallback. Both spellings commander accepts are checked.
+*/
+function errorOutputIsJson(state, argv) {
+	if (state.config) return state.config.output === "json";
+	const flag = argv.indexOf("--output");
+	if (flag !== -1 && argv[flag + 1] === "json") return true;
+	if (argv.includes("--output=json")) return true;
+	return configuredOutput() === "json";
+}
+function renderedHelp({ showAll = false } = {}) {
 	let out = "";
+	showAllCommands = showAll;
 	const program = buildProgram();
 	program.configureOutput({
 		writeOut: (str) => {
@@ -9648,10 +10491,12 @@ function renderedHelp() {
 		writeErr: () => {}
 	});
 	program.outputHelp();
+	showAllCommands = false;
 	return out;
 }
 /** Full root help text (what `busabase-cli --help` prints). Generated from the command tree. */
 const HELP = renderedHelp();
+renderedHelp({ showAll: true });
 /**
 * Turn a low-level transport/HTTP error into an actionable message: which host was tried, the
 * concrete next step (set a key for Cloud, point at a local server, or check connectivity), and a
@@ -9661,7 +10506,7 @@ function explainError(error, config) {
 	const base = config.baseUrl;
 	const rawMessage = error instanceof Error ? error.message : String(error);
 	const issueDetail = formatIssues(error.data?.issues);
-	const msg = issueDetail ? `${rawMessage} — ${issueDetail}` : rawMessage;
+	const msg = issueDetail && !rawMessage.includes(issueDetail) ? `${rawMessage} — ${issueDetail}` : rawMessage;
 	const status = error.status;
 	const lower = msg.toLowerCase();
 	let body;