busa-cli 0.40.1 → 0.41.0

package/dist/{update-check-CDXOWtw_.js → update-check-BR-m6M4r.js}

@@ -17,6 +17,7 @@ import { parse, stringify } from "yaml";
 import { checkAirApp } from "busabase-sdk/airapp-check";
 import { fileURLToPath } from "node:url";
 import { Uint8ArrayReader, ZipReader } from "@zip.js/zip.js";
+import QRCode from "qrcode";
 const LocaleSchema = z.enum({
 	defaultLocale: "en",
 	locales: [
@@ -106,8 +107,8 @@ const iStringSchema = z.union([z.string(), iStringRecordSchema]).describe("i18n
 //#region ../../packages/busabase-contract/src/contract/node-agent-prompt-schemas.ts
 /**
 * Per-node custom scenario prompts (`node.metadata.agentPrompts`) — the single
-* schema shared by BOTH write and read paths, per
-* `apps/busabase-cloud/content/spec/node-agent-prompts-v2.md` §7.3:
+* schema shared by BOTH write and read paths, per the node-agent-prompts
+* design (v2) §7.3:
 *
 * - Write: `busabase-cli nodes set-agent-prompts` validates a file against this
 *   schema client-side, before calling `nodes.updateMetadata` — a malformed file
@@ -219,7 +220,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$5 = (input) => {
+const mergeIntent$6 = (input) => {
 	if (input.requireReview) return { autoMerge: false };
 	if (input.autoMerge) return { autoMerge: true };
 	return {};
@@ -244,7 +245,7 @@ const baseFieldChangeTask = {
 	name: "base_field_change_request",
 	cliPath: ["bases", "field-change-request"],
 	summary: "Propose a Base schema change (add / update / delete / convert / reorder / restore)",
-	guidance: "Review is permission-aware for add / update / reorder / restore, decided server-side: the change merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise — check the response's `status`. Pass requireReview to always propose instead. `delete` and `convert` are ALWAYS review-first regardless of permission, by design: delete soft-deletes the field's stored values with it, and convert can drop values. Pick `operation` first, then supply only that operation's arguments — add needs slug+name; update needs fieldId+patch; delete/restore need fieldId; convert needs fieldId+newType; reorder needs the complete fieldIds order. Before a convert, `bases_preview_field_conversion` shows what the data would become.",
+	guidance: "Review is permission-aware for every operation, decided server-side: the change merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise — check the response's `status`. Pass requireReview to always propose instead. Worth doing on `delete` and `convert` when the data matters: delete soft-deletes the field's stored values with it (restore brings both back), and convert can drop values that do not fit the new type. Pick `operation` first, then supply only that operation's arguments — add needs slug+name; update needs fieldId+patch; delete/restore need fieldId; convert needs fieldId+newType; reorder needs the complete fieldIds order. Before a convert, `bases_preview_field_conversion` shows what the data would become.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -372,30 +373,12 @@ const baseFieldChangeTask = {
 		{
 			name: "autoMerge",
 			kind: "boolean",
-			appliesWhen: {
-				param: "operation",
-				values: [
-					"add",
-					"update",
-					"reorder",
-					"restore"
-				]
-			},
 			description: "Skip review and apply the schema change immediately if you have write access. Not a permission override — a changeRequest-level key still gets a pending CR. Default is permission-aware: merge when you can, otherwise propose."
 		},
 		{
 			name: "requireReview",
 			kind: "boolean",
-			appliesWhen: {
-				param: "operation",
-				values: [
-					"add",
-					"update",
-					"reorder",
-					"restore"
-				]
-			},
-			description: "Always propose a pending ChangeRequest, even with write access. delete and convert are review-first regardless."
+			description: "Always propose a pending ChangeRequest, even with write access. Worth passing on delete and convert when the field holds data you would not want dropped without a second look."
 		}
 	],
 	examples: [
@@ -409,7 +392,7 @@ const baseFieldChangeTask = {
 			baseId: input.baseId,
 			...input.message ? { message: input.message } : {},
 			...input.submittedBy ? { submittedBy: input.submittedBy } : {},
-			...mergeIntent$5(input)
+			...mergeIntent$6(input)
 		};
 		switch (input.operation) {
 			case "add": return client.bases.fieldChangeRequest({
@@ -799,10 +782,10 @@ const nodeReadFileTask = {
 * off — but a CLI boolean flag is presence-only, so `--auto-merge` alone could
 * never express "forced off". Same two-flag shape as `node_create`.
 *
-* 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.
+* Applies to every operation kind, deletes included — a delete batch used to be
+* pinned review-first server-side regardless of this flag, and no longer is.
 */
-const mergeIntent$4 = (input) => {
+const mergeIntent$5 = (input) => {
 	if (input.requireReview) return { autoMerge: false };
 	if (input.autoMerge) return { autoMerge: true };
 	return {};
@@ -828,7 +811,7 @@ const nodeFilesChangeRequestTask = {
 		}
 	],
 	summary: "Propose file changes inside a Skill, Drive, or AirApp node",
-	guidance: "Review is permission-aware, decided server-side: the change merges immediately when your key has write access on the node and lands as a pending ChangeRequest otherwise — check the response's `status`. Pass requireReview to always propose instead. A batch containing a `delete` is ALWAYS review-first regardless of permission, by design — deleting a mounted file destroys content, and a batch is never partially merged. Each operation is one of create / update / delete / metadata_update. Include `baseContentHash` (from `node_file_read`) on an update so a concurrent edit is caught. For kind \"airapp\", keep the project runnable by `npm run dev` — editing package.json must leave a \"dev\" script starting a plain Node server, not a bundler dev server.",
+	guidance: "Review is permission-aware, decided server-side: the change merges immediately when your key has write access on the node and lands as a pending ChangeRequest otherwise — check the response's `status`. Pass requireReview to always propose instead — worth doing for a batch containing a `delete`, since that removes a mounted file (its previous bytes stay in the change request's history, and a batch is never partially merged). Each operation is one of create / update / delete / metadata_update. Include `baseContentHash` (from `node_file_read`) on an update so a concurrent edit is caught. For kind \"airapp\", keep the project runnable by `npm run dev` — editing package.json must leave a \"dev\" script starting a plain Node server, not a bundler dev server.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -872,7 +855,7 @@ const nodeFilesChangeRequestTask = {
 			operations: input.operations,
 			...input.message ? { message: input.message } : {},
 			...input.submittedBy ? { submittedBy: input.submittedBy } : {},
-			...mergeIntent$4(input)
+			...mergeIntent$5(input)
 		};
 		return client.fileTrees.createChangeRequest(payload);
 	}
@@ -1118,11 +1101,21 @@ const nodeShareTask = {
 };
 //#endregion
 //#region ../../packages/busabase-contract/src/tasks/node-archive.ts
+/**
+* `autoMerge` is tri-state — unset (permission-aware default), forced on, forced
+* off — but a CLI boolean flag is presence-only, so `--auto-merge` alone could
+* never express "forced off". Same two-flag shape as `node_create`.
+*/
+const mergeIntent$4 = (input) => {
+	if (input.requireReview) return { autoMerge: false };
+	if (input.autoMerge) return { autoMerge: true };
+	return {};
+};
 const nodeArchiveTask = {
 	name: "node_archive",
 	cliPath: ["nodes", "archive"],
 	summary: "Archive a node (reversible; the node moves to Trash)",
-	guidance: "This is the only way to move a node into the archived state, and it is reversible — the node appears in the Trash view and can be restored. It is review-first by default: it proposes a ChangeRequest for a human unless you pass autoMerge. Do NOT use node_purge to remove a node: purge is permanent and only accepts a node that has ALREADY been archived by this task.",
+	guidance: "This is the only way to move a node into the archived state, and it is reversible — the node appears in the Trash view and can be restored. Review is permission-aware, decided server-side: it archives immediately when your key has write access on the node and lands as a pending ChangeRequest otherwise. Pass requireReview to always propose instead. Do NOT use node_purge to remove a node: purge is permanent and only accepts a node that has ALREADY been archived by this task.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -1147,14 +1140,19 @@ const nodeArchiveTask = {
 		{
 			name: "autoMerge",
 			kind: "boolean",
-			description: "Archive immediately instead of proposing a ChangeRequest for review."
+			description: "Archive immediately if you have write access. Not a permission override — a changeRequest-level key still gets a pending CR. Default is permission-aware: archive when you can, otherwise propose."
+		},
+		{
+			name: "requireReview",
+			kind: "boolean",
+			description: "Always propose a pending ChangeRequest instead of archiving, even with write access."
 		}
 	],
-	examples: ["busabase-cli nodes archive --node-id nod_123", "busabase-cli nodes archive --node-id nod_123 --auto-merge   # skip review"],
+	examples: ["busabase-cli nodes archive --node-id nod_123", "busabase-cli nodes archive --node-id nod_123 --require-review   # leave it for a human"],
 	execute: async (client, input) => client.nodes.createChangeRequest({
 		message: input.message ?? "Archive node",
 		submittedBy: input.submittedBy,
-		autoMerge: Boolean(input.autoMerge),
+		...mergeIntent$4(input),
 		operations: [{
 			kind: "delete",
 			nodeId: input.nodeId
@@ -1383,7 +1381,7 @@ const folderNodeType = {
 /**
 * Form node: an agent-authored, sandboxed web page bound to a Base via an
 * explicit field-binding contract. A submission does NOT write a record
-* directly — it produces an approval-first record-create ChangeRequest on the
+* directly — it produces a review-first record-create ChangeRequest on the
 * target Base (so the submitting act reuses the base's `record_create` op, not a
 * form-specific one). The form's own config (bindings/page/share) is owner-
 * managed and edited directly, so this node contributes no CR operations of its
@@ -1659,7 +1657,7 @@ const nodeCreateTask = {
 		}
 	],
 	summary: "Create a workspace node of any type",
-	guidance: "One call creates any of the 11 node types with its type-specific payload: `fields` for a Base, `body` for a Doc, `files` for a Skill/Drive/AirApp, `assetId` for a File. Busabase is approval-first: by default this proposes a ChangeRequest for a human to review, and only merges immediately when you already have write access. Pass requireReview to always propose instead of merging.",
+	guidance: "One call creates any of the 11 node types with its type-specific payload: `fields` for a Base, `body` for a Doc, `files` for a Skill/Drive/AirApp, `assetId` for a File. Review is permission-aware, decided server-side: this merges immediately when you already have write access on the parent node, and proposes a ChangeRequest for a human otherwise. Pass requireReview to always propose instead of merging.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -1969,7 +1967,7 @@ const recordChangeTask = {
 	name: "record_change_request",
 	cliPath: ["records", "change-request"],
 	summary: "Propose a change to an existing record (update / delete / restore)",
-	guidance: "Review is permission-aware, decided server-side: `update` merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise — check the response's `materialized` field to see which happened. Pass explicit `autoMerge: false` to force review even when you could write directly. `delete` and `restore` are always review-first regardless of permission, by design. `delete` ARCHIVES the record — it is reversible with `restore`, not an erase. For update, `fields` is keyed by field slug and only needs the fields you are changing; if you set the Base's PRIMARY (first) field, keep it a short human-readable title.",
+	guidance: "Review is permission-aware for all three operations, decided server-side: the change merges immediately when your key has write access on the Base's node and lands as a pending ChangeRequest otherwise — check the response's `materialized` field to see which happened. Pass explicit `autoMerge: false` to force review even when you could write directly. `delete` ARCHIVES the record — it is reversible with `restore`, not an erase. For update, `fields` is keyed by field slug and only needs the fields you are changing; if you set the Base's PRIMARY (first) field, keep it a short human-readable title.",
 	annotations: {
 		readOnly: false,
 		destructive: false
@@ -2010,20 +2008,12 @@ const recordChangeTask = {
 		{
 			name: "autoMerge",
 			kind: "boolean",
-			appliesWhen: {
-				param: "operation",
-				values: ["update"]
-			},
-			description: "Skip review and apply the update immediately if you have write access. Not a permission override — a changeRequest-level key still gets a pending CR. Default is permission-aware: merge when you can, otherwise propose."
+			description: "Skip review and apply the change immediately if you have write access. Not a permission override — a changeRequest-level key still gets a pending CR. Default is permission-aware: merge when you can, otherwise propose."
 		},
 		{
 			name: "requireReview",
 			kind: "boolean",
-			appliesWhen: {
-				param: "operation",
-				values: ["update"]
-			},
-			description: "Always propose a pending ChangeRequest for this update, even with write access. delete/restore are review-first regardless."
+			description: "Always propose a pending ChangeRequest instead of applying the change, even with write access."
 		}
 	],
 	examples: [
@@ -2049,11 +2039,13 @@ const recordChangeTask = {
 		if (input.operation === "delete") return client.records.changeRequest({
 			...common,
 			operation: "delete",
-			deleteMode: "archive"
+			deleteMode: "archive",
+			...mergeIntent$1(input)
 		});
 		return client.records.changeRequest({
 			...common,
-			operation: "restore"
+			operation: "restore",
+			...mergeIntent$1(input)
 		});
 	}
 };
@@ -3074,7 +3066,7 @@ z.object({ ok: z.boolean() });
 //#region src/retry.ts
 const BASE_DELAY_MS = 500;
 const MAX_DELAY_MS = 2e4;
-const READ_METHODS = /* @__PURE__ */ new Set([
+const READ_METHODS$1 = /* @__PURE__ */ new Set([
 	"GET",
 	"HEAD",
 	"OPTIONS"
@@ -3111,7 +3103,7 @@ function parseRetryAfter(header, now = Date.now()) {
 /** 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;
+	if (!READ_METHODS$1.has(method.toUpperCase())) return false;
 	return status === void 0 || status >= 500;
 }
 /**
@@ -4369,6 +4361,145 @@ function banner(baseUrl) {
 	return out.join("\n");
 }
 //#endregion
+//#region src/contract-catalog.ts
+const isProcedure = (node) => typeof node === "object" && node !== null && typeof node["~orpc"]?.route?.method === "string";
+/** `spaceId` → `space-id`. Shared so command names and `schema` agree. */
+const kebab = (value) => value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+/** Depth-first walk of the contract tree, yielding every procedure it holds. */
+function* contractProcedures(node = cloudContract, navPath = []) {
+	for (const key of Object.keys(node)) {
+		if (key === "~orpc") continue;
+		const child = node[key];
+		if (isProcedure(child)) yield {
+			id: [...navPath, key].join("."),
+			navPath,
+			key,
+			proc: child
+		};
+		else if (child && typeof child === "object") yield* contractProcedures(child, [...navPath, key]);
+	}
+}
+/**
+* The CLI command a contract procedure is reachable as: the top-level group plus
+* a leaf whose name folds any deeper contract groups into itself, so
+* `nodes.principals.list` is `busabase-cli nodes principals-list` (not a third
+* command level). Mirrors `addLeaf` in `run.ts`.
+*
+* This is the *generated* spelling. A curated task command may supersede it under
+* a friendlier name, which is why `schema` labels the field "generated command".
+*/
+function generatedCommandPath(navPath, key) {
+	if (navPath.length === 0) return [kebab(key)];
+	return [kebab(navPath[0]), [...navPath.slice(1), key].map(kebab).join("-")];
+}
+/**
+* Resolve a live request back to the contract endpoint that serves it, so an
+* error can name the endpoint even when the command that failed was a curated
+* task (which may call several endpoints and therefore declares none).
+*
+* Matches the route's `{param}` segments positionally. When more than one route
+* fits, the one with the most *literal* segments matched wins, so a concrete
+* `/nodes/favorites` is never shadowed by a parameterized `/nodes/{nodeId}`.
+* Ties are impossible: two routes with identical literals at identical positions
+* and the same length are the same route.
+*/
+function matchRoute(method, pathname) {
+	const wanted = pathname.split("?")[0].split("/").filter(Boolean);
+	let best;
+	for (const entry of contractProcedures()) {
+		const { route } = entry.proc["~orpc"];
+		if (route.method.toUpperCase() !== method.toUpperCase()) continue;
+		const segments = route.path.split("/").filter(Boolean);
+		if (segments.length !== wanted.length) continue;
+		let literals = 0;
+		if (segments.every((segment, index) => {
+			if (segment.startsWith("{") && segment.endsWith("}")) return true;
+			if (segment !== wanted[index]) return false;
+			literals += 1;
+			return true;
+		}) && (!best || literals > best.literals)) best = {
+			entry,
+			literals
+		};
+	}
+	return best?.entry;
+}
+//#endregion
+//#region src/dry-run.ts
+/** Methods that change nothing, and so run for real even under `--dry-run`. */
+const READ_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
+/**
+* Thrown by {@link dryRunFetch} instead of performing a write. Carries the plan
+* so the caller can print it. Deliberately not an `Error` subclass that any retry
+* or transient-failure predicate would match — see `retry.ts`'s `isTransientError`.
+*/
+var DryRunInterception = class extends Error {
+	plan;
+	constructor(plan) {
+		super(`dry run: ${plan.method} ${plan.url} was not sent`);
+		this.name = "DryRunInterception";
+		this.plan = plan;
+	}
+};
+const readBody = (init) => {
+	const body = init?.body;
+	if (body === void 0 || body === null) return void 0;
+	if (typeof body !== "string") return `<${typeof body} body>`;
+	try {
+		return JSON.parse(body);
+	} catch {
+		return body;
+	}
+};
+/** Wrap a fetch so the first mutating request throws {@link DryRunInterception}. */
+function dryRunFetch(inner) {
+	return async (input, init) => {
+		const request = input instanceof Request ? input : void 0;
+		const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+		if (READ_METHODS.has(method)) return inner(input, init);
+		throw new DryRunInterception({
+			method,
+			url: request?.url ?? String(input),
+			body: readBody(init)
+		});
+	};
+}
+/** What a human (or an agent) sees instead of the write happening. */
+function renderDryRunPlan(plan) {
+	const lines = ["[busabase-cli] --dry-run: nothing was sent. This is the request that would have gone out:", `  ${plan.method} ${plan.url}`];
+	if (plan.body !== void 0) lines.push("  body:", JSON.stringify(plan.body, null, 2));
+	return lines.join("\n");
+}
+/**
+* Note printed when `--dry-run` was asked for but the command never tried to
+* write. Silence would read as "the write was suppressed"; it was not — the
+* output the command printed is real data from a real read.
+*/
+const DRY_RUN_NO_WRITE_NOTE = "[busabase-cli] --dry-run: this command sent no write, so nothing was suppressed — the output above is real.";
+/**
+* Record every request's method and path. A curated task command may call several
+* endpoints, so the one that actually failed is only knowable from the wire —
+* which is what lets a `403` name the endpoint (and its required permission level)
+* for tasks too, not just for the generated endpoint commands.
+*/
+function observeRequests(inner, sink) {
+	return async (input, init) => {
+		const request = input instanceof Request ? input : void 0;
+		const url = request?.url ?? String(input);
+		try {
+			sink({
+				method: (init?.method ?? request?.method ?? "GET").toUpperCase(),
+				pathname: new URL(url).pathname
+			});
+		} catch {}
+		return inner(input, init);
+	};
+}
+//#endregion
 //#region src/errors.ts
 /**
 * Process exit code per class.
@@ -4481,7 +4612,8 @@ function errorEnvelope(classified) {
 		...classified.status !== void 0 ? { status: classified.status } : {},
 		message: classified.message,
 		...classified.issues ? { issues: classified.issues } : {},
-		retryable: classified.retryable
+		retryable: classified.retryable,
+		...classified.hint ? { hint: classified.hint } : {}
 	};
 }
 /**
@@ -4686,6 +4818,13 @@ const BUSABASE_CLI_CLIENT_ID = "busabase-cli";
 *
 * Both end the same way: verify against `/api/v1/auth`, pick the target space, and
 * write `BUSABASE_BASE_URL` / `BUSABASE_API_KEY` / `BUSABASE_SPACE_ID`.
+*
+* Device authorization additionally splits into a **two-turn agent flow**:
+* `--no-wait` starts it and returns the verification URL plus a resume code at
+* once (no blocking, no credential written), and `--resume-code <code>` finishes
+* it in a later invocation. This exists because many agent harnesses only relay
+* a turn's FINAL message — a URL printed mid-command while this process blocks
+* polling never reaches the user, so the blocking flow silently times out.
 */
 const OAUTH_TIMEOUT_MS = 3e5;
 /** Env key holding the OAuth access-token expiry (ISO), used to drive built-in auto-refresh. */
@@ -4882,8 +5021,10 @@ const delay = (durationMs) => new Promise((resolve) => setTimeout(resolve, durat
 async function readDeviceResponse(response) {
 	return await response.json().catch(() => ({}));
 }
-/** RFC 8628 login: no local callback and no credential ever written to output. */
-async function deviceLogin(baseUrl, useBrowser) {
+/** Fallback lifetime for a device code when the server does not declare one. */
+const DEVICE_CODE_TTL_SECONDS = 900;
+/** Step 1 of RFC 8628: ask the server for a device code + verification URL. */
+async function requestDeviceAuthorization(baseUrl) {
 	const origin = new URL(baseUrl).origin;
 	let codeResponse;
 	try {
@@ -4904,17 +5045,26 @@ async function deviceLogin(baseUrl, useBrowser) {
 	const code = await codeResponse.json().catch(() => ({}));
 	if (!codeResponse.ok) throw new Error(`Could not start device sign-in (HTTP ${codeResponse.status})${code.error_description ? `: ${code.error_description}` : "."}`);
 	if (!code.device_code || !code.user_code || !code.verification_uri) throw new Error("Device sign-in returned an incomplete authorization response.");
-	const verificationUrl = code.verification_uri_complete ?? code.verification_uri;
-	say("");
-	say("Authorize Busabase CLI in any browser:");
-	say(`  ${code.verification_uri}`);
-	say(`  Code: ${code.user_code}`);
-	say("");
-	if (useBrowser) openBrowser(verificationUrl);
-	say("Waiting for authorization…");
-	const expiresInSeconds = Math.max(1, code.expires_in ?? 900);
-	const deadline = Date.now() + expiresInSeconds * 1e3;
-	let intervalSeconds = Math.max(1, code.interval ?? 5);
+	return {
+		deviceCode: code.device_code,
+		userCode: code.user_code,
+		verificationUri: code.verification_uri,
+		verificationUrl: code.verification_uri_complete ?? code.verification_uri,
+		expiresInSeconds: Math.max(1, code.expires_in ?? DEVICE_CODE_TTL_SECONDS),
+		intervalSeconds: Math.max(1, code.interval ?? 5)
+	};
+}
+/**
+* Step 2 of RFC 8628: poll until the user approves, then finalize into an API
+* key. Callable on its own for `--resume-code` (the device code outlives this
+* process server-side, so resuming needs no new endpoint). `restartCommand`
+* names the exact command to rerun once a code has expired — a resumed sign-in
+* must not tell the user to plain "run login" and silently drop their flags.
+*/
+async function pollDeviceApiKey(baseUrl, auth, restartCommand) {
+	const origin = new URL(baseUrl).origin;
+	const deadline = Date.now() + auth.expiresInSeconds * 1e3;
+	let intervalSeconds = auth.intervalSeconds;
 	let consecutiveNetworkFailures = 0;
 	let pendingPollCount = 0;
 	let reassuredAfterApprovalHint = false;
@@ -4931,14 +5081,14 @@ async function deviceLogin(baseUrl, useBrowser) {
 				},
 				body: JSON.stringify({
 					grant_type: "urn:ietf:params:oauth:grant-type:device_code",
-					device_code: code.device_code,
+					device_code: auth.deviceCode,
 					client_id: BUSABASE_CLI_CLIENT_ID
 				})
 			});
 			consecutiveNetworkFailures = 0;
 		} catch {
 			consecutiveNetworkFailures += 1;
-			if (consecutiveNetworkFailures >= 3) throw new Error("Device sign-in lost its network connection. Check connectivity and run `busabase-cli login` again.");
+			if (consecutiveNetworkFailures >= 3) throw new Error(`Device sign-in lost its network connection. Check connectivity and run \`${restartCommand}\` again.`);
 			continue;
 		}
 		const payload = await readDeviceResponse(tokenResponse);
@@ -4949,7 +5099,7 @@ async function deviceLogin(baseUrl, useBrowser) {
 					authorization: `Bearer ${payload.access_token}`,
 					"content-type": "application/json"
 				},
-				body: JSON.stringify({ deviceCode: code.device_code })
+				body: JSON.stringify({ deviceCode: auth.deviceCode })
 			});
 			const finalized = await finalizeResponse.json().catch(() => ({}));
 			if (!finalizeResponse.ok || !finalized.apiKey || finalized.credentialType !== "api_key") {
@@ -4973,11 +5123,24 @@ async function deviceLogin(baseUrl, useBrowser) {
 				intervalSeconds += 5;
 				continue;
 			case "access_denied": throw new Error("Device sign-in was denied. No credential was saved.");
-			case "expired_token": throw new Error("The device code expired. Run `busabase-cli login` to request a new one.");
+			case "expired_token": throw new Error(`The device code expired. Run \`${restartCommand}\` to request a new one.`);
 			default: throw new Error(`Device sign-in failed${payload.error_description ? `: ${payload.error_description}` : ` (HTTP ${tokenResponse.status})`}.`);
 		}
 	}
-	throw new Error("The device code expired. Run `busabase-cli login` to request a new one.");
+	throw new Error(`The device code expired. Run \`${restartCommand}\` to request a new one.`);
+}
+/** RFC 8628 login: no local callback and no credential ever written to output. */
+async function deviceLogin(baseUrl, useBrowser, profile) {
+	const auth = await requestDeviceAuthorization(baseUrl);
+	say("");
+	say("Authorize Busabase CLI in any browser:");
+	say(`  ${auth.verificationUri}`);
+	say(`  Code: ${auth.userCode}`);
+	say("");
+	if (useBrowser) openBrowser(auth.verificationUrl);
+	if (!isInteractive()) say(`[AI agent] This command blocks (up to ${Math.round(auth.expiresInSeconds / 60)} minutes) until the user approves in a browser. If your harness only delivers a turn's final message, the user will never see the URL above. Instead run \`${buildLoginCommand(baseUrl, profile, "--no-wait --output json")}\`, send verification_url to the user as your final message, end the turn, and finish later with \`--resume-code\`. Do not restart login after showing the URL — a restart invalidates it.`);
+	say("Waiting for authorization…");
+	return pollDeviceApiKey(baseUrl, auth, buildLoginCommand(baseUrl, profile, ""));
 }
 /** Exchange a rotating refresh token for a new OAuth token set. */
 async function refreshToken(baseUrl, refreshToken) {
@@ -5020,14 +5183,37 @@ function pickSpaceId(verify, preselected) {
 	return fallback;
 }
 /**
+* Assemble a copy-paste-runnable `busabase-cli login …` for THIS connection —
+* non-default base URL and active profile included — so an agent (or the JSON
+* error envelope) never hands the user a command that targets the wrong host
+* or the wrong account.
+*/
+const buildLoginCommand = (baseUrl, profile, suffix) => {
+	const parts = ["busabase-cli login"];
+	if (normalizeBaseUrl(baseUrl) !== normalizeBaseUrl(DEFAULT_BASE_URL)) parts.push(`--base-url ${normalizeBaseUrl(baseUrl)}`);
+	if (profile) parts.push(`--profile ${profile}`);
+	if (suffix) parts.push(suffix);
+	return parts.join(" ");
+};
+/**
+* Machine-readable next step for an auth failure, attached to the JSON error
+* envelope (the human prose in `explainError` stays as-is). Written for an
+* agent recovering without a terminal: the two-turn device flow is the one
+* path that works when only a turn's final message reaches the user.
+*/
+function authRecoveryHint(code, baseUrl, profile, endpoint) {
+	if (code === "FORBIDDEN") return "The credential was accepted but lacks permission for this action. " + (endpoint?.procedureId && endpoint.level ? `\`${endpoint.procedureId}\` requires an API key at level \`${endpoint.level}\`${endpoint.declared ? "" : " (no explicit policy for it; the server fails closed to this)"}. Check yours with \`busabase-cli whoami\`. ` : "") + "Confirm the target space (`busabase-cli space list`, then `busabase-cli space use <id>`), or ask a space admin to issue a key at the level above. Note a `changeRequest`-level key can propose but deliberately cannot merge its own proposal.";
+	return `Run \`${buildLoginCommand(baseUrl, profile, "--no-wait --output json")}\` to get verification_url and resume_code. Show verification_url to the user EXACTLY as returned (an opaque string — never re-encode, trim, or re-wrap it) and end this turn so they can approve it on any device. After they confirm, run \`${buildLoginCommand(baseUrl, profile, "--resume-code <resume_code>")}\` to finish signing in, then retry this command. Do not restart login after showing the URL — a restart invalidates it. For headless automation, pass --api-key <token> from the environment instead.`;
+}
+/**
 * Interactive "where is your Busabase?" menu. Every option resolves to the same two
 * axes: which base URL, and how (if at all) to obtain a token — the rest of login just
 * writes that to ~/.busabase/.env.
 */
 async function chooseTarget() {
 	const cloud = normalizeBaseUrl(DEFAULT_BASE_URL);
-	say("Busabase is an approval-first database and knowledge base for AI agents.");
-	say("Agents propose changes; humans review and merge what becomes trusted data.");
+	say("Busabase is your AI agents' database, knowledge base, apps library, and skills registry.");
+	say("Every change goes in as a change request, so it keeps a message, a diff, and a history.");
 	say("This login connects the CLI to the Busabase instance you want to use.");
 	say("");
 	say("How should this CLI connect?");
@@ -5074,8 +5260,23 @@ async function chooseTarget() {
 async function runLogin(options) {
 	let baseUrl = normalizeBaseUrl(options.baseUrl);
 	let apiKey = options.apiKey;
+	if (options.noWait && apiKey) throw new Error("--no-wait starts a device sign-in and cannot be combined with --api-key.");
+	if (options.noWait && options.resumeCode) throw new Error("--no-wait and --resume-code are the two halves of one sign-in — pass one, not both.");
+	if (options.noWait) {
+		const auth = await requestDeviceAuthorization(baseUrl);
+		const resume = buildLoginCommand(baseUrl, options.profile, `--resume-code ${auth.deviceCode}`);
+		return {
+			status: "authorization pending",
+			verification_url: auth.verificationUrl,
+			user_code: auth.userCode,
+			resume_code: auth.deviceCode,
+			expires_in: String(auth.expiresInSeconds),
+			hint: `Show verification_url to the user EXACTLY as returned — it is an opaque string; never re-encode, trim, or re-wrap it — then END THIS TURN so they can approve it on any device (a QR code helps: \`busabase-cli qrcode <verification_url> --out-file qr.png\`). After the user confirms, run \`${resume}\` to finish signing in. Do NOT start a new login in the meantime — a fresh login invalidates this link.`
+		};
+	}
 	let method;
-	if (apiKey) method = "api-key";
+	if (options.resumeCode) method = "device-resume";
+	else if (apiKey) method = "api-key";
 	else if (options.deviceCode) method = "device";
 	else if (options.oauth) method = "loopback-oauth";
 	else if (isInteractive()) {
@@ -5104,7 +5305,16 @@ async function runLogin(options) {
 	let apiKeyExpiresAt;
 	let refreshTokenValue;
 	if (method === "device") {
-		const result = await deviceLogin(baseUrl, options.browser);
+		const result = await deviceLogin(baseUrl, options.browser, options.profile);
+		token = result.token;
+		apiKeyExpiresAt = result.apiKeyExpiresAt;
+	} else if (method === "device-resume") {
+		say("Resuming device sign-in…");
+		const result = await pollDeviceApiKey(baseUrl, {
+			deviceCode: options.resumeCode ?? "",
+			intervalSeconds: 5,
+			expiresInSeconds: DEVICE_CODE_TTL_SECONDS
+		}, buildLoginCommand(baseUrl, options.profile, "--no-wait"));
 		token = result.token;
 		apiKeyExpiresAt = result.apiKeyExpiresAt;
 	} else if (method === "loopback-oauth") {
@@ -5135,8 +5345,8 @@ async function runLogin(options) {
 	say(`✓ Signed in and saved to ${activeCredentialPath()}`);
 	return {
 		status: "signed in",
-		method: method === "loopback-oauth" ? "oauth" : method,
-		credentialType: method === "device" ? "api_key" : expiresAt ? "oauth" : "api_key",
+		method: method === "loopback-oauth" ? "oauth" : method === "device-resume" ? "device" : method,
+		credentialType: method === "device" || method === "device-resume" ? "api_key" : expiresAt ? "oauth" : "api_key",
 		user: verify.user?.email ?? verify.user?.name ?? verify.user?.id ?? "(unknown)",
 		space: spaceId ?? "(server default)",
 		availableSpaces: (verify.spaces ?? []).map((space) => `${space.name} [${space.id}]`).join(", "),
@@ -5698,24 +5908,30 @@ const PACKAGE_SIDECARS = PACKAGE_SKILL_SIDECAR_DIRS.join("|");
 //#endregion
 //#region ../../packages/busabase-contract/src/contract/auto-merge.ts
 /**
-* `autoMerge` on an operation that deliberately never auto-merges.
-*
-* These schemas are NOT `.strict()` — and making them strict is not the fix. The
-* SDK and CLI ship on their own npm cadence (published ahead of the server as of
-* writing), and busabase is self-hosted, so a newer client sending a newer
-* optional field to an older server is normal traffic. Blanket strictness turns
-* that graceful degradation into a hard 400 for every field, to catch one.
-*
-* So reject exactly the field that actually confused callers, and say WHY plus
-* what to do instead — an agent reading "unrecognized key: autoMerge" learns
-* nothing it can act on, which is how the original silent-drop bug survived.
-*
-* Rejects `true` only. An explicit `false` asks for exactly what these operations
-* already do, so refusing it would be pedantry with a cost: every review-first
-* call site in this repo passes a uniform `autoMerge: false`, and clients that do
-* the same must not start collecting 400s on the subset of endpoints where the
-* flag happens to be moot. Same forward-compatibility argument that rules out
-* blanket `.strict()`.
+* `autoMerge` on a destructive-but-reversible operation.
+*
+* These six operations (record delete/restore, field delete/convert, Base
+* archive, mounted-asset content edits, and file batches containing a delete)
+* used to reject `autoMerge: true` outright: they queued for human review no
+* matter who called them. That made sense while the product was positioned as
+* approval-first, but it is not how Busabase is positioned or how the rest of
+* the write surface behaves — every other write is *permission-aware*
+* (`shouldAutoMerge`): unset + write access on the target node means "just do
+* it", and only an explicit `false` forces review.
+*
+* A single person running their own workspace hit the old behaviour as pure
+* friction: archiving one duplicate record left a change request they then had
+* to go and approve themselves. Reversibility is what makes the permission-aware
+* default safe here — delete ARCHIVES, archive is undone by restore, and a
+* field convert is preceded by `previewFieldConversion`. Callers who do want a
+* second pair of eyes still get it by passing an explicit `autoMerge: false`,
+* which is exactly how every other endpoint in this family expresses that.
+*
+* The schemas that use this are NOT `.strict()`, and making them strict is not
+* the fix: the SDK and CLI ship on their own npm cadence and busabase is
+* self-hosted, so a newer client sending a newer optional field to an older
+* server is normal traffic. Blanket strictness turns that graceful degradation
+* into a hard 400 for every field, to catch one.
 *
 * This lives in its own leaf module (zod only, no sibling imports) on purpose:
 * putting it in `contract/schemas.ts` created an import cycle with the domain
@@ -5723,7 +5939,7 @@ const PACKAGE_SIDECARS = PACKAGE_SKILL_SIDECAR_DIRS.join("|");
 * `ReferenceError: Cannot access 'autoMergeNotAccepted' before initialization`
 * that `tsc` reported as clean.
 */
-const autoMergeNotAccepted = (reason) => z.literal(false, { error: `\`autoMerge: true\` is not accepted here: ${reason}` }).optional().describe(`Only \`false\` (or omitted) is accepted. ${reason}`);
+const destructiveAutoMerge = (undoNote) => z.boolean().optional().describe(`Whether to approve and merge this change immediately. Omitted defaults to merging immediately if the actor has write access on the target node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. ${undoNote}`);
 //#endregion
 //#region ../../packages/busabase-contract/src/domains/base/contract/base-schemas.ts
 const fieldNameSchema = z.union([z.string().min(1), iStringRecordSchema.refine((record) => Object.values(record).some((value) => value && value.trim().length > 0), "field name must have at least one non-empty locale value")]);
@@ -5870,16 +6086,13 @@ const createBaseFieldInputSchema = z.object({
 * node, otherwise falls back to a pending ChangeRequest. Explicit `false` forces
 * review even with write access.
 *
-* Deliberately NOT on the `delete` and `convert` branches below. The line this
-* codebase already draws — record `update` auto-merges, record `delete`/`restore`
-* never do, and `assets.editContent` never does — is about whether CONTENT data
-* is at stake, not about the verb. Adding, renaming, reordering, or un-deleting a
-* field touches only the schema; deleting one soft-deletes its stored values with
-* it, and converting one can drop values outright (which is why
-* `previewFieldConversion` exists as a dry run). Those two stay in front of a
-* human.
+* The `delete` and `convert` branches below used to reject `autoMerge` outright.
+* They no longer do — see `contract/auto-merge.ts` for why. They carry a
+* `destructiveAutoMerge` schema instead: the same tri-state, with a description
+* that says what the operation costs to undo, so a caller who genuinely wants a
+* second pair of eyes knows to pass `false`.
 */
-const fieldAutoMergeSchema = z.boolean().optional().describe("Whether to approve and merge this field change immediately. Omitted defaults to merging immediately if the actor has write access on the Base's node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access. Not accepted by the delete and convert operations, which always require review.");
+const fieldAutoMergeSchema = z.boolean().optional().describe("Whether to approve and merge this field change immediately. Omitted defaults to merging immediately if the actor has write access on the Base's node, otherwise falling back to a pending Change Request; pass explicit false to force review even with write access.");
 const createFieldChangeRequestInputSchema = createBaseFieldInputSchema.extend({
 	message: z.string().optional().default("Add field"),
 	submittedBy: z.string().optional().default("local-editor"),
@@ -5889,7 +6102,7 @@ const deleteFieldChangeRequestInputSchema = z.object({
 	fieldId: z.string().min(1),
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
-	autoMerge: autoMergeNotAccepted("deleting a field soft-deletes its stored values with it, so it always requires review. Omit the flag.")
+	autoMerge: destructiveAutoMerge("A deleted field is soft-deleted with its stored values and is brought back by the `restore` operation.")
 });
 const updateFieldChangeRequestInputSchema = z.object({
 	fieldId: z.string().min(1),
@@ -5904,7 +6117,15 @@ const updateFieldChangeRequestInputSchema = z.object({
 });
 z.object({
 	fieldId: z.string().min(1),
-	newType: fieldTypeSchema
+	newType: fieldTypeSchema,
+	/**
+	* Mirrors `convertFieldChangeRequest.selectChoiceMode` so the dry run models the
+	* conversion the caller is actually going to submit. Under `auto_create` a value with
+	* no matching choice is not a conflict — the merge mints a choice for it — while under
+	* `null_on_missing` the same value is dropped. Defaults to `null_on_missing`, matching
+	* the mutation's own default.
+	*/
+	selectChoiceMode: z.enum(["auto_create", "null_on_missing"]).default("null_on_missing")
 });
 z.object({
 	totalCount: z.number(),
@@ -5921,7 +6142,7 @@ const convertFieldChangeRequestInputSchema = z.object({
 	selectChoiceMode: z.enum(["auto_create", "null_on_missing"]).default("null_on_missing"),
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
-	autoMerge: autoMergeNotAccepted("converting a field's type can drop values, so it always requires review. Run previewFieldConversion first to see what would change, then omit the flag.")
+	autoMerge: destructiveAutoMerge("A convert can drop values that do not fit the new type — call `previewFieldConversion` first to see exactly which, and pass `autoMerge: false` if you want a human to sign off on that preview.")
 });
 const reorderFieldsChangeRequestInputSchema = z.object({
 	fieldIds: z.array(z.string()).min(1),
@@ -5932,7 +6153,7 @@ const reorderFieldsChangeRequestInputSchema = z.object({
 const archiveBaseInputSchema = z.object({
 	message: z.string().optional(),
 	submittedBy: z.string().optional().default("local-editor"),
-	autoMerge: autoMergeNotAccepted("archiving a Base removes it and every record in it from every listing at once, so it always requires review. Omit the flag.")
+	autoMerge: destructiveAutoMerge("Archiving takes the Base and every record in it out of every listing at once. That is reversible via `operation: \"restore\"`, but it is the widest-blast-radius write in this family — pass `autoMerge: false` when it should stop for a human.")
 });
 const restoreBaseInputSchema = z.object({
 	message: z.string().optional(),
@@ -6037,7 +6258,8 @@ const nodeSchema = z.lazy(() => z.object({
 	updatedAt: z.string(),
 	baseId: z.string().nullable(),
 	children: z.array(nodeSchema),
-	hasChildren: z.boolean().optional()
+	hasChildren: z.boolean().optional(),
+	shared: z.boolean().optional()
 }));
 z.object({
 	id: z.string(),
@@ -6315,6 +6537,51 @@ const commentSchema = z.object({
 	createdAt: z.string(),
 	updatedAt: z.string()
 });
+/**
+* One row of the Inbox's Mentions tab: a comment the caller was `@`-mentioned
+* in, plus where to go to read it in context.
+*
+* Keyed by COMMENT, not by mention row — being named twice in one comment is
+* legitimate (each occurrence needs its own span to render its own chip), but
+* it is still one thing to go read, so it is one entry here.
+*/
+const mentionInboxItemSchema = z.object({
+	commentId: z.string(),
+	subjectType: commentSubjectTypeSchema,
+	/** Comment body, for the row's preview line. */
+	body: z.string(),
+	authorId: z.string(),
+	author: userRefSchema.nullable().optional().default(null),
+	createdAt: z.string(),
+	/** Null once read. The newest unread stamp across this comment's mentions. */
+	unread: z.boolean(),
+	/**
+	* Dashboard-relative path to the comment's context, or null when the subject
+	* has no page of its own (a `commit`-scoped comment on a comment that is not
+	* attached to a change request — the repo has no commit detail route).
+	* A null href still renders a row: swallowing the notification because we
+	* cannot link it would leave the recipient never knowing they were mentioned.
+	*/
+	href: z.string().nullable()
+});
+z.object({
+	items: z.array(mentionInboxItemSchema),
+	total: z.number().int(),
+	/** Distinct unread comments — what the tab badge shows. */
+	unreadCount: z.number().int()
+});
+z.object({
+	page: z.number().int().min(1).optional().default(1),
+	pageSize: z.number().int().min(1).max(100).optional().default(50)
+});
+z.object({ 
+/** Stamps every unread mention row this caller has on that comment. */
+commentId: z.string() });
+z.object({
+	/** How many rows were stamped; 0 when it was already read. */
+	marked: z.number().int(),
+	unreadCount: z.number().int()
+});
 const changeRequestStatusSchema = z.enum([
 	"in_review",
 	"changes_requested",
@@ -6530,7 +6797,7 @@ z.object({
 	message: z.string().optional().default("Delete record").describe("Explanation shown to the human reviewer. Say what is being removed and why, e.g. \"Archive duplicate contact — merged into Acme Corp\"."),
 	submittedBy: z.string().optional().default("local-producer"),
 	deleteMode: z.enum(["archive"]).optional().default("archive"),
-	autoMerge: autoMergeNotAccepted("archiving a record removes user content from every listing, so it always requires review. Omit the flag.")
+	autoMerge: destructiveAutoMerge("Archiving is reversible: the record leaves every listing but is restored intact by `operation: \"restore\"`.")
 });
 z.object({
 	fields: z.record(z.string(), z.unknown()).describe("Updated field values keyed by field slug. If you set the base's PRIMARY field (its first field), keep it a short human-readable name — it is the record's display title everywhere."),
@@ -10700,6 +10967,379 @@ async function paginateAll(options) {
 	return written;
 }
 //#endregion
+//#region src/qrcode-command.ts
+/**
+* `busabase-cli qrcode <url>` — render a URL as a QR code.
+*
+* Exists for one moment: an agent has a login `verification_url` and the human
+* who must approve it is holding a phone. A QR code removes the copy-a-long-URL
+* step entirely. The URL is treated as an OPAQUE string — encoded byte-for-byte,
+* never re-encoded, trimmed, or re-assembled — because a "helpfully" reworded
+* URL is a 404 on the user's phone.
+*/
+/** Same shape as lark-cli's hint: generating the file alone is a classic agent miss. */
+const QR_DISPLAY_HINT = "You MUST include this QR image in your reply to the user — generating the file alone is not enough. Show the URL first (verbatim — it is an opaque string; never re-encode, trim, or re-wrap it) and place the QR image below it.";
+const QR_MAX_SIZE = 1024;
+/**
+* A `--out-file` path may live under the working directory, the OS temp
+* directory, or the user's home — the places an agent legitimately writes
+* artifacts. Anything else (e.g. `/etc/...`) is refused rather than written.
+*/
+function safeQrOutputPath(raw) {
+	const abs = resolve(raw);
+	if (![
+		process.cwd(),
+		tmpdir(),
+		homedir()
+	].some((root) => {
+		const prefix = root.endsWith(sep) ? root : root + sep;
+		return abs === root || abs.startsWith(prefix);
+	})) throw new Error(`Unsafe --out-file path "${raw}" — write inside the current directory, ${tmpdir()}, or your home directory.`);
+	return abs;
+}
+/** Encode `url` into a PNG at `filePath` (path must already be validated). */
+async function writeQrPng(url, filePath, size) {
+	if (!Number.isInteger(size) || size < 64 || size > 1024) throw new Error(`--size must be an integer between 64 and ${QR_MAX_SIZE}.`);
+	await QRCode.toFile(filePath, url, {
+		type: "png",
+		width: size,
+		errorCorrectionLevel: "M"
+	});
+}
+/** Encode `url` as a small terminal (ANSI half-block) QR code. */
+async function renderQrAscii(url) {
+	return QRCode.toString(url, {
+		type: "terminal",
+		small: true,
+		errorCorrectionLevel: "M"
+	});
+}
+z.object({
+	level: z.enum([
+		"read",
+		"changeRequest",
+		"write",
+		"manage"
+	]),
+	nodeScope: z.array(z.string()).optional()
+}).nullable();
+z.object({ level: z.enum([
+	"read",
+	"changeRequest",
+	"write",
+	"manage"
+]) }).strict().nullable();
+/**
+* Explicit path → level+scope table for every current procedure. Nothing is
+* inferred from HTTP method: POST grep/preview routes can be reads, while GET
+* Webhook/Vault configuration routes are manage. Any unknown path defaults to
+* workspace manage, and the parity test prevents contract additions from
+* remaining unknown in reviewed code. Keyed by the dotted path *relative to
+* `busabaseRouter`* (e.g. `"bases.create"`, `"changeRequests.merge"`) — see
+* `resolveRequiredLevel` for why the real oRPC `path` seen at runtime carries
+* a leading `"workbench"` mount-key segment that must be stripped first.
+*
+* Enumerated against the real `packages/busabase-core/src/router.ts` +
+* every `packages/busabase-contract/src/domains/*​/contract.ts` route
+* definition (not guessed) — see the implementation report for the full
+* cross-check, including known method/semantics deviations:
+*   - `dump.exportTables` is a POST route in the real contract (the design
+*     doc's prose called it a GET) — already force-classified to `manage`
+*     below either way, so this doesn't change behavior, just the reasoning.
+*   - The top-level `grep` route is POST because it takes a request body, but
+*     is explicitly classified as a node-scoped read.
+*/
+const node = (level) => ({
+	level,
+	scope: "node"
+});
+const workspace = (level) => ({
+	level,
+	scope: "workspace"
+});
+/**
+* Exhaustive policy for the current Busabase contract. A contract-parity test
+* fails when a procedure is added without an explicit decision here.
+*/
+const PROCEDURE_PERMISSION_POLICY = {
+	"auth.verify": workspace("read"),
+	search: node("read"),
+	grep: node("read"),
+	"nodes.list": node("read"),
+	"nodes.get": node("read"),
+	"nodes.getAgentPrompts": node("read"),
+	"nodes.searchByName": node("read"),
+	"nodes.isDescendant": node("read"),
+	"nodes.ancestors": node("read"),
+	"nodes.resolveRouteState": node("read"),
+	"nodes.createChangeRequest": node("changeRequest"),
+	"operations.revise": node("changeRequest"),
+	"bases.createChangeRequest": node("changeRequest"),
+	"bases.createBulkChangeRequest": node("changeRequest"),
+	"bases.createBulkUpdateChangeRequest": node("changeRequest"),
+	"bases.fieldChangeRequest": node("changeRequest"),
+	"bases.lifecycleChangeRequest": node("changeRequest"),
+	"records.changeRequest": node("changeRequest"),
+	"views.changeRequest": node("changeRequest"),
+	"nodes.updateContent": node("changeRequest"),
+	"fileTrees.createChangeRequest": node("changeRequest"),
+	"assets.createUploadUrl": workspace("changeRequest"),
+	"assets.confirm": workspace("changeRequest"),
+	"nodes.icon.createUploadUrl": node("changeRequest"),
+	"nodes.icon.confirm": node("changeRequest"),
+	"assets.putText": node("write"),
+	"assets.createTextUploadUrl": node("write"),
+	"changeRequests.review": node("write"),
+	"changeRequests.merge": node("write"),
+	"changeRequests.close": node("write"),
+	"bases.create": node("write"),
+	"bases.createField": node("write"),
+	"docs.create": node("write"),
+	"fileTrees.create": node("write"),
+	"files.create": node("write"),
+	"nodes.move": node("write"),
+	"nodes.updateMetadata": node("write"),
+	"nodes.updateSettings": node("write"),
+	"nodes.updateAgentPrompts": node("write"),
+	"nodes.toggleFavorite": node("write"),
+	"comments.create": node("write"),
+	"auditEvents.create": workspace("manage"),
+	"assets.updateMetadata": node("write"),
+	"assets.delete": node("write"),
+	"assets.editContent": node("write"),
+	"webhooks.list": workspace("manage"),
+	"webhooks.get": workspace("manage"),
+	"webhooks.create": workspace("manage"),
+	"webhooks.update": workspace("manage"),
+	"webhooks.delete": workspace("manage"),
+	"webhooks.deliveries": workspace("manage"),
+	"webhooks.testFire": workspace("manage"),
+	"vault.get": workspace("manage"),
+	"vault.update": workspace("manage"),
+	"vault.clear": workspace("manage"),
+	"dump.exportTables": workspace("manage"),
+	"dump.exportAssetText": workspace("manage"),
+	"dump.exportDocBodies": workspace("manage"),
+	"dump.importBegin": workspace("manage"),
+	"dump.importTables": workspace("manage"),
+	"dump.importCommit": workspace("manage"),
+	"dump.importAbort": workspace("manage"),
+	"nodes.purge": node("manage"),
+	"nodes.updateVisibility": node("manage"),
+	"nodes.principals.list": node("manage"),
+	"nodes.principals.add": node("manage"),
+	"nodes.principals.remove": node("manage"),
+	"nodes.share.get": node("manage"),
+	"nodes.share.set": node("manage"),
+	"nodes.share.disable": node("manage"),
+	"embedLinks.create": workspace("manage"),
+	"embedLinks.list": workspace("manage"),
+	"embedLinks.revoke": workspace("manage"),
+	"nodes.listFavorites": node("read"),
+	"auditEvents.list": node("read"),
+	"activity.listPaged": node("read"),
+	"activity.listForNode": node("read"),
+	"activity.listForRecord": node("read"),
+	"comments.list": node("read"),
+	"comments.listMentions": node("read"),
+	"comments.markMentionsRead": node("read"),
+	"agent.listTasks": node("read"),
+	"live.subscribe": workspace("manage"),
+	"bases.list": node("read"),
+	"bases.get": node("read"),
+	"bases.listDeletedFields": node("read"),
+	"bases.listViews": node("read"),
+	"bases.previewFieldConversion": node("read"),
+	"fileTrees.listFiles": node("read"),
+	"fileTrees.readFile": node("read"),
+	"airapps.runLocal": node("write"),
+	"airapps.stopLocal": node("write"),
+	"nodes.readLines": node("read"),
+	"forms.list": node("read"),
+	"forms.getByNode": node("read"),
+	"forms.create": node("manage"),
+	"forms.update": node("manage"),
+	"forms.submit": node("changeRequest"),
+	"assets.list": node("read"),
+	"assets.get": node("read"),
+	"assets.download": node("read"),
+	"assets.readTextLines": node("read"),
+	"install.planFromGithub": workspace("read"),
+	"install.fromGithub": workspace("manage"),
+	"templates.list": workspace("read"),
+	"guides.list": workspace("read"),
+	"guides.read": workspace("read"),
+	"agents.catalog": workspace("manage"),
+	"agents.connections.list": workspace("manage"),
+	"agents.disconnect": workspace("manage"),
+	"agents.sessions.list": workspace("manage"),
+	"agents.sessions.create": workspace("manage"),
+	"agents.sessions.prompt": workspace("manage"),
+	"agents.sessions.cancel": workspace("manage"),
+	"agents.sessions.close": workspace("manage"),
+	"agents.sessions.subscribe": workspace("manage"),
+	"agents.sessions.respondToPermission": workspace("manage"),
+	"changeRequests.list": node("read"),
+	"changeRequests.listPage": node("read"),
+	"changeRequests.inboxSnapshot": node("read"),
+	"changeRequests.counts": node("read"),
+	"changeRequests.get": node("read"),
+	"records.list": node("read"),
+	"records.listPage": node("read"),
+	"records.count": node("read"),
+	"records.groupBy": node("read"),
+	"records.get": node("read"),
+	"records.search": node("read"),
+	"records.listChangeRequests": node("read"),
+	"records.listLinks": node("read")
+};
+/** Backward-compatible level-only export used by older tests/callers. */
+const PROCEDURE_LEVEL_OVERRIDES = Object.fromEntries(Object.entries(PROCEDURE_PERMISSION_POLICY).map(([path, policy]) => [path, policy.level]));
+/**
+* `workbenchProcedure.router(busabaseRouter)` is later spread into the
+* `workbench` key of the router the host actually serves, and oRPC resolves
+* `path` against the FULL served router tree, not the sub-router the
+* middleware was attached to — confirmed empirically against both
+* `OpenAPIHandler` and `RPCHandler` (the two handlers actually used in
+* production): a call to `workbench.bases.create` delivers
+* `path: ["workbench", "bases", "create"]` to the middleware, not
+* `["bases", "create"]` as originally assumed. Strip that one known mount-key
+* segment; leave any other shape untouched (e.g. a future direct mount, or a
+* unit test that passes a bare `busabaseRouter`-relative path).
+*/
+const normalizePath = (path) => path[0] === "workbench" ? path.slice(1) : [...path];
+/**
+* Backward-compatible level-only resolver. HTTP method is deliberately ignored:
+* known paths use the explicit semantic policy and unknown paths fail closed to
+* manage regardless of whether they happen to be GET, POST, or RPC-only.
+*/
+function resolveRequiredLevel(path, _routeMethod) {
+	const key = normalizePath(path).join(".");
+	const override = PROCEDURE_LEVEL_OVERRIDES[key];
+	if (override) return override;
+	return "manage";
+}
+//#endregion
+//#region src/schema-command.ts
+/**
+* The level an endpoint needs, from the contract's own policy table — the same
+* table the server enforces with, so this can never disagree with a real 403.
+*
+* A handful of endpoints have no explicit entry and the policy fails closed to
+* `manage`. That is the right answer for the gate, but a *guess* as far as advice
+* goes, so callers that phrase it for a human should know which it is.
+*/
+function requiredLevelFor(id) {
+	return {
+		level: resolveRequiredLevel(id.split("."), void 0),
+		declared: id in PROCEDURE_PERMISSION_POLICY
+	};
+}
+/** Zod → JSON Schema. `io` matters: defaults/coercion make input and output differ. */
+function toJsonSchema(schema, io) {
+	if (schema === void 0) return void 0;
+	try {
+		return z.toJSONSchema(schema, {
+			io,
+			unrepresentable: "any"
+		});
+	} catch {
+		return;
+	}
+}
+const describe = (entry) => {
+	const { route } = entry.proc["~orpc"];
+	return {
+		id: entry.id,
+		method: route.method,
+		path: route.path,
+		...route.summary ? { summary: route.summary } : {},
+		...route.successDescription ? { description: route.successDescription } : {},
+		command: `busabase-cli ${generatedCommandPath(entry.navPath, entry.key).join(" ")}`,
+		requiredLevel: requiredLevelFor(entry.id).level
+	};
+};
+/** Every endpoint the contract carries, in contract order. */
+function listEndpoints() {
+	return [...contractProcedures()].map(describe);
+}
+/**
+* Resolve a user-typed id. Accepts the dotted contract path (`bases.list`), the
+* space-separated form (`bases list`, already joined by the caller), and the
+* kebab spelling the command tree uses (`change-requests.list`), so an agent can
+* paste back whatever it saw without translating.
+*/
+function findEntry(query) {
+	const normalize = (value) => value.replace(/[\s/]+/g, ".").replace(/-/g, "").toLowerCase();
+	const wanted = normalize(query);
+	const entries = [...contractProcedures()];
+	return entries.find((entry) => entry.id === query) ?? entries.find((entry) => normalize(entry.id) === wanted);
+}
+/** Ids closest to a miss, so the error can suggest instead of just refusing. */
+function suggestions(query, limit = 5) {
+	const needle = query.replace(/[\s./-]+/g, "").toLowerCase();
+	if (!needle) return [];
+	const scored = [];
+	for (const entry of contractProcedures()) {
+		const hay = entry.id.replace(/[.-]/g, "").toLowerCase();
+		if (hay.includes(needle)) scored.push({
+			id: entry.id,
+			score: 0
+		});
+		else if (needle.length >= 3 && hay.includes(needle.slice(0, 3))) scored.push({
+			id: entry.id,
+			score: 1
+		});
+	}
+	return scored.sort((a, b) => a.score - b.score || a.id.length - b.id.length).slice(0, limit).map((s) => s.id);
+}
+/**
+* A misspelled id is a usage error, not a runtime failure: it exits `2` like any
+* other bad argument, so a script can tell "you typed it wrong" from "the call failed".
+*/
+var SchemaNotFoundError = class extends CliOutcomeError {
+	constructor(query, near) {
+		super("USAGE", near.length ? `Unknown endpoint "${query}". Did you mean: ${near.join(", ")}? Run \`busabase-cli schema\` for the full list.` : `Unknown endpoint "${query}". Run \`busabase-cli schema\` for the full list.`);
+		this.name = "SchemaNotFoundError";
+	}
+};
+/** One endpoint, with the halves the caller asked for. */
+function describeEndpoint(query, io) {
+	const entry = findEntry(query);
+	if (!entry) throw new SchemaNotFoundError(query, suggestions(query));
+	const { inputSchema, outputSchema } = entry.proc["~orpc"];
+	return {
+		...describe(entry),
+		...io === "output" ? {} : { input: toJsonSchema(inputSchema, "input") },
+		...io === "input" ? {} : { output: toJsonSchema(outputSchema, "output") }
+	};
+}
+/** Human-readable rendering for a terminal; `--output json` prints the object instead. */
+function renderEndpoint(endpoint) {
+	const lines = [
+		`${endpoint.id}`,
+		`  ${endpoint.method} ${endpoint.path}`,
+		...endpoint.summary ? [`  ${endpoint.summary}`] : [],
+		...endpoint.description ? [`  ${endpoint.description}`] : [],
+		`  command: ${endpoint.command}`,
+		`  requires API key level: ${endpoint.requiredLevel}`
+	];
+	if (endpoint.input !== void 0) lines.push("", "input:", JSON.stringify(endpoint.input, null, 2));
+	if (endpoint.output !== void 0) lines.push("", "output:", JSON.stringify(endpoint.output, null, 2));
+	return lines.join("\n");
+}
+/** The endpoint index, one line each — the map before you pick a target. */
+function renderList(entries) {
+	const width = Math.max(...entries.map((e) => e.id.length));
+	return [
+		...entries.map((e) => `${e.id.padEnd(width)}  ${e.method.padEnd(6)} ${e.path}${e.summary ? `  — ${e.summary}` : ""}`),
+		"",
+		`${entries.length} endpoints. \`busabase-cli schema <id>\` prints one endpoint's input and output schema.`
+	].join("\n");
+}
+/** Exported for the help text, so the example ids can never name a dead endpoint. */
+const sampleEndpointId = () => findEntry("bases.list")?.id ?? [...contractProcedures()][0]?.id ?? "bases.list";
+//#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. */
@@ -10794,6 +11434,7 @@ const registerOne = (program, task, deps, path, preset = {}, summaryOverride) =>
 		}
 		applyParam(cmd, param);
 	}
+	if (!task.annotations.readOnly) cmd.option("--dry-run", "print the request this would send and send nothing");
 	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, {
@@ -11062,10 +11703,10 @@ function parseJsonValue(raw, flagName) {
 * Render a validation error's per-issue detail as `path: message`.
 *
 * Load-bearing, not cosmetic: a schema that refuses a field explains WHY in the
-* issue message (e.g. "`autoMerge` is not accepted here: deleting a field
-* soft-deletes its stored values with it… Omit the flag."). Without this the
-* caller sees only the generic envelope "Input validation failed" and is no
-* better off than when the field was silently dropped.
+* issue message (e.g. "deleteMode: Invalid option: expected \"archive\"" — hard
+* delete after retention was never implemented). Without this the caller sees
+* only the generic envelope "Input validation failed" and is no better off than
+* when the field was silently dropped.
 */
 function formatIssues(issues) {
 	const parsed = toIssues(issues);
@@ -11222,14 +11863,28 @@ function runAction(state, handler) {
 		if (refreshedToken) config.apiKey = refreshedToken;
 		state.config = config;
 		assertCredentialNotExpired(config.apiKey);
+		const dryRun = Boolean(opts.dryRun);
+		config.fetch = observeRequests(config.fetch ?? fetch, (seen) => {
+			state.lastRequest = seen;
+		});
+		if (dryRun) config.fetch = dryRunFetch(config.fetch);
 		const client = createBusabaseClient(config);
-		if (opts.all) {
-			await streamAllPages(client, opts, config, handler);
-			return;
+		try {
+			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 (dryRun) console.error(DRY_RUN_NO_WRITE_NOTE);
+			if (opts.wait) await awaitReview(client, opts, config, result);
+		} catch (error) {
+			if (!(error instanceof DryRunInterception)) throw error;
+			console.log(config.output === "json" ? render({
+				dryRun: true,
+				wouldSend: error.plan
+			}, config.output) : renderDryRunPlan(error.plan));
 		}
-		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. */
@@ -11316,9 +11971,6 @@ function pkgVersion() {
 		return "0.0.0";
 	}
 }
-/** camelCase → kebab-case for flag and command names (createChangeRequest → create-change-request). */
-const kebab = (value) => value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-const isProcedure = (node) => typeof node === "object" && node !== null && typeof node["~orpc"]?.route?.method === "string";
 /** Peel ZodOptional/ZodDefault/ZodNullable wrappers; a default or optional wrapper means not-required. */
 function unwrapSchema(schema) {
 	let inner = schema;
@@ -11474,6 +12126,12 @@ const GENERATED_SKIP = /* @__PURE__ */ new Set([
 	"fileTrees.readFile",
 	"fileTrees.createChangeRequest"
 ]);
+/** Routes that change nothing — they run for real under `--dry-run`, so no flag is offered. */
+const READ_ROUTE_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"OPTIONS"
+]);
 /** Walk `cloudContract` and register a leaf command per procedure not already covered by hand. */
 function registerGeneratedCommands(program, state) {
 	const getGroup = (displayName, tag) => program.commands.find((c) => c.name() === displayName) ?? program.command(displayName).description(tag ?? `${displayName} endpoints`);
@@ -11524,8 +12182,11 @@ function registerGeneratedCommands(program, state) {
 			}
 		}
 		addGlobalFlags(leaf);
-		leaf.addHelpText("after", `\nOpenAPI: ${route.method} ${route.path}`);
+		if (!READ_ROUTE_METHODS.has(route.method.toUpperCase())) leaf.option("--dry-run", "print the request this would send and send nothing");
+		const procedureId = [...navPath, procKey].join(".");
+		leaf.addHelpText("after", `\nOpenAPI: ${route.method} ${route.path}\nRequires API key level: ${requiredLevelFor(procedureId).level}`);
 		leaf.action(runAction(state, (client, opts) => {
+			state.procedureId = procedureId;
 			let input = {};
 			for (const f of fields) {
 				if (f.pinned !== void 0) {
@@ -11544,19 +12205,10 @@ function registerGeneratedCommands(program, state) {
 			return fields.length > 0 ? target[procKey](input) : target[procKey]();
 		}));
 	};
-	const walk = (node, navPath) => {
-		for (const key of Object.keys(node)) {
-			if (key === "~orpc") continue;
-			const child = node[key];
-			const id = [...navPath, key].join(".");
-			if (isProcedure(child)) {
-				if (GENERATED_SKIP.has(id)) continue;
-				const parent = navPath.length ? getGroup(kebab(navPath[0]), child["~orpc"].route.tags?.[0]) : program;
-				addLeaf(parent, navPath, key, child);
-			} else if (child && typeof child === "object") walk(child, [...navPath, key]);
-		}
-	};
-	walk(cloudContract, []);
+	for (const { id, navPath, key, proc } of contractProcedures()) {
+		if (GENERATED_SKIP.has(id)) continue;
+		addLeaf(navPath.length ? getGroup(kebab(navPath[0]), proc["~orpc"].route.tags?.[0]) : program, navPath, key, proc);
+	}
 }
 /**
 * Per-command flag signature derived from the actual option definitions, e.g.
@@ -11628,14 +12280,42 @@ function buildProgram(state = {}) {
 	addGlobalFlags(program);
 	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("schema")).argument("[endpoint...]", "contract id, e.g. `bases.list` or `bases list`; omit to list all").description("Print one endpoint's input/output schema — offline, no credential").addOption(new Option("--io <half>", "print only one half of the schema").choices(["input", "output"])).addHelpText("after", `
+Answers "what do I send, and what comes back" without fetching anything. The
+contract is compiled into this CLI, so \`schema\` works offline and unauthenticated.
+
+Prefer it over \`busabase-cli openapi\`: that returns the WHOLE document — 936 KB
+across 103 endpoints as of 2026-09-04, with every type inlined per endpoint — so
+reading one endpoint's arguments out of it costs roughly 234k tokens. One
+endpoint through \`schema\` is a few KB.
+
+  busabase-cli schema                                 # every endpoint: id, method, path
+  busabase-cli schema ${sampleEndpointId()}                       # input + output schema
+  busabase-cli schema records.changeRequest --io input  # just what to send
+  busabase-cli schema records list --output json       # machine-readable
+
+Ids are the contract path. \`schema\` also accepts the space-separated and kebab
+spellings, so you can paste back whatever you saw.`).action((endpoint, _opts, cmd) => {
+		const opts = cmd.optsWithGlobals();
+		const config = resolveConfig(opts);
+		state.config = config;
+		const io = opts.io;
+		if (!endpoint || endpoint.length === 0) {
+			const entries = listEndpoints();
+			console.log(config.output === "json" ? render(entries, config.output) : renderList(entries));
+			return;
+		}
+		const described = describeEndpoint(endpoint.join("."), io);
+		console.log(config.output === "json" ? render(described, config.output) : renderEndpoint(described));
+	});
 	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", `
+	addGlobalFlags(program.command("guide")).argument("[topic]", "which guide to read; omit to list the topics this server serves").description("Read the Busabase operating manual (workspace conventions, 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 workspace       # the change-request workflow
   busabase-cli guide airapp          # REQUIRED before writing any AirApp file`).action(async (topic, _opts, cmd) => {
 		const config = resolveConfig(cmd.optsWithGlobals());
 		state.config = config;
@@ -11652,9 +12332,9 @@ Examples:
 		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.
+	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)").option("--no-wait", "start a device sign-in and return verification_url + resume_code at once (for agents)").option("--resume-code <code>", "finish a device sign-in started earlier with --no-wait").addHelpText("after", `
+Busabase is your AI agents' database, knowledge base, apps library, and skills registry.
+Every change goes in as a change request, so it keeps a message, a diff, and a history.
 
 Run interactively, login explains the connection choices and writes the selected
 Busabase instance to ~/.busabase/.env:
@@ -11672,10 +12352,20 @@ The flags below skip the menu (handy for scripts / CI):
   busabase-cli login --base-url http://localhost:15419 # connect to a local server (no auth)
   busabase-cli login --refresh                         # rotate the OAuth token set (auto-runs too)
   busabase-cli login --profile work                    # add a SECOND account, then switch to it
+  busabase-cli login --no-wait --output json           # agent: URL + resume code, returns at once
+  busabase-cli login --resume-code <code>              # agent: finish after the user authorized
 
 Login never blocks on a Space question, interactive or not: with more than one Space it always
 accepts the server-resolved default (the one you were most recently active in) and prints the
-full list — switch anytime with \`busabase-cli space use <id>\`.`).action(async (_opts, cmd) => {
+full list — switch anytime with \`busabase-cli space use <id>\`.
+
+For AI agents: the blocking flows above print the verification URL mid-command, and
+a harness that only relays a turn's final message will drop it — the user never
+sees the URL and login silently times out. Use the two-turn flow instead: run
+\`--no-wait --output json\` now, send verification_url to the user as your final
+message (verbatim — never re-encode or re-wrap it; \`busabase-cli qrcode\` renders
+it scannable), end the turn, then run \`--resume-code <code>\` after they confirm.
+Do not restart login after showing the URL — a restart invalidates it.`).action(async (_opts, cmd) => {
 		const opts = cmd.optsWithGlobals();
 		const config = resolveConfig(opts);
 		state.config = config;
@@ -11688,7 +12378,10 @@ full list — switch anytime with \`busabase-cli space use <id>\`.`).action(asyn
 			spaceId: config.spaceId,
 			deviceCode: Boolean(opts.deviceCode),
 			oauth: Boolean(opts.oauth),
-			browser: opts.browser !== false
+			browser: opts.browser !== false,
+			noWait: opts.wait === false,
+			resumeCode: opts.resumeCode,
+			profile: opts.profile
 		});
 		const profile = opts.profile;
 		if (profile && !opts.refresh) activateLoggedInProfile(profile);
@@ -11703,6 +12396,33 @@ full list — switch anytime with \`busabase-cli space use <id>\`.`).action(asyn
 		});
 		console.log(render(summary, config.output));
 	});
+	addGlobalFlags(program.command("qrcode")).description("Render a URL (e.g. a login verification URL) as a QR code").argument("<url>", "URL to encode — treated as an opaque string, byte-for-byte").option("-o, --out-file <path>", "write a PNG here (under cwd, the temp dir, or your home)").option("--ascii", "print a terminal QR code to stdout instead of writing a PNG").option("--size <px>", `PNG size in pixels (64-${QR_MAX_SIZE}, default 256)`, parsePositiveInt).addHelpText("after", `
+Made for the two-turn login: \`login --no-wait\` returns a verification_url the
+user often approves on a phone — a QR code removes the copy-a-long-URL step.
+
+  busabase-cli qrcode "<verification_url>" --out-file qr.png
+  busabase-cli qrcode "<verification_url>" --ascii
+
+Forward URLs verbatim: never re-encode, trim, or re-wrap a verification URL —
+a reworded URL is a 404 on the user's phone.`).action(async (url, _opts, cmd) => {
+		const opts = cmd.optsWithGlobals();
+		const config = resolveConfig(opts);
+		state.config = config;
+		if (opts.ascii) {
+			console.log(await renderQrAscii(url));
+			return;
+		}
+		const outFile = opts.outFile;
+		if (!outFile) throw new Error("Pass --out-file <path> for a PNG, or --ascii for terminal output.");
+		const filePath = safeQrOutputPath(outFile);
+		await writeQrPng(url, filePath, opts.size ?? 256);
+		console.log(render({
+			status: "qr code written",
+			filePath,
+			url,
+			hint: QR_DISPLAY_HINT
+		}, config.output));
+	});
 	const auth = program.command("auth").description("Accounts (profiles) and CLI settings");
 	const authStatus = (cmd) => cmd.action(async (_opts, sub) => {
 		const config = resolveConfig(sub.optsWithGlobals());
@@ -11767,11 +12487,11 @@ than as a 403 later. The choice is stored in the active profile and mirrored to
 	});
 	const nodes = program.command("nodes").description("Workspace node tree");
 	addGlobalFlags(nodes.command("list")).description("Workspace node tree").action(runAction(state, (client) => client.nodes.list()));
-	addGlobalFlags(nodes.command("purge")).description("Permanently delete an ALREADY-archived node and its subtree (irreversible). Archive it first with `nodes archive` if it isn't archived yet.").requiredOption("--node-id <id>", "archived node id to purge").action(runAction(state, (client, opts) => client.nodes.purge({ nodeId: opts.nodeId })));
+	addGlobalFlags(nodes.command("purge")).description("Permanently delete an ALREADY-archived node and its subtree (irreversible). Archive it first with `nodes archive` if it isn't archived yet.").requiredOption("--node-id <id>", "archived node id to purge").option("--dry-run", "print the request this would send and send nothing").action(runAction(state, (client, opts) => client.nodes.purge({ nodeId: opts.nodeId })));
 	addGlobalFlags(nodes.command("move")).description("Move or reorder a node (applied immediately, no review needed)").requiredOption("--node-id <id>", "node id to move").option("--parent-node-id <id>", "new parent folder node id; omit to keep the current parent").option("--position <n>", "new position among the target parent's children", (v) => Number.parseInt(v, 10)).option("--message <text>", "Change Request message").option("--submitted-by <name>", "producer label").addHelpText("after", `
 Examples:
   busabase-cli nodes move --node-id nod_123 --position 0
-  busabase-cli nodes move --node-id nod_123 --parent-node-id nod_456 --position 2`).action(runAction(state, (client, opts) => client.nodes.move({
+  busabase-cli nodes move --node-id nod_123 --parent-node-id nod_456 --position 2`).option("--dry-run", "print the request this would send and send nothing").action(runAction(state, (client, opts) => client.nodes.move({
 		nodeId: opts.nodeId,
 		parentNodeId: opts.parentNodeId,
 		position: opts.position,
@@ -11793,7 +12513,7 @@ locale) is reported entry-by-entry and nothing is written. \`--file\`'s
 contents ARE the array to store; this command does not reshape it.
 
 Examples:
-  busabase-cli nodes set-agent-prompts --node-id nod_123 --file prompts.json`).action(runAction(state, async (client, opts) => {
+  busabase-cli nodes set-agent-prompts --node-id nod_123 --file prompts.json`).option("--dry-run", "print the request this would send and send nothing").action(runAction(state, async (client, opts) => {
 		const filePath = opts.file;
 		let raw;
 		try {
@@ -11828,7 +12548,7 @@ Examples:
 		if (!found) throw new Error(`no Base with slug "${slug}"`);
 		return found;
 	}));
-	addGlobalFlags(bases.command("create-field")).description("Add a field to a Base").requiredOption("--base-id <id>", "Base id").requiredOption("--slug <slug>", "field slug").requiredOption("--name <name>", "field name").option("--field-type <type>", "field type (default text)").option("--required", "mark the field as required").option("--max-files <n>", "attachment option: max files", parsePositiveInt).option("--max-file-size <bytes>", "attachment option: max size in bytes", parsePositiveInt).option("--allowed-mime <mime>", "attachment option: allowed MIME type, repeatable", collectValues).action(runAction(state, (client, opts) => client.bases.createField({
+	addGlobalFlags(bases.command("create-field")).description("Add a field to a Base").requiredOption("--base-id <id>", "Base id").requiredOption("--slug <slug>", "field slug").requiredOption("--name <name>", "field name").option("--field-type <type>", "field type (default text)").option("--required", "mark the field as required").option("--max-files <n>", "attachment option: max files", parsePositiveInt).option("--max-file-size <bytes>", "attachment option: max size in bytes", parsePositiveInt).option("--allowed-mime <mime>", "attachment option: allowed MIME type, repeatable", collectValues).option("--dry-run", "print the request this would send and send nothing").action(runAction(state, (client, opts) => client.bases.createField({
 		baseId: opts.baseId,
 		slug: opts.slug,
 		name: opts.name,
@@ -11839,7 +12559,7 @@ Examples:
 	addGlobalFlags(bases.command("update-field-change-request")).description("Propose updating field metadata/options via a Change Request").requiredOption("--base-id <id>", "Base id").requiredOption("--field-id <id>", "field id").option("--name <name>", "new field name").option("--required <true|false>", "set required flag", parseBoolean).option("--options-json <json|@file>", "full field options JSON, or @file.json").option("--max-files <n>", "attachment option: max files", parsePositiveInt).option("--max-file-size <bytes>", "attachment option: max size in bytes", parsePositiveInt).option("--allowed-mime <mime>", "attachment option: allowed MIME type, repeatable", collectValues).option("--message <text>", "reviewer-facing Change Request message").option("--submitted-by <name>", "producer label").addHelpText("after", `
 Examples:
   busabase-cli bases update-field-change-request --base-id bse_123 --field-id bsf_123 --name "封面 Cover Image" --max-files 1 --allowed-mime image/png --allowed-mime image/svg+xml
-  busabase-cli bases update-field-change-request --base-id bse_123 --field-id bsf_123 --options-json @field-options.json`).action(runAction(state, (client, opts) => {
+  busabase-cli bases update-field-change-request --base-id bse_123 --field-id bsf_123 --options-json @field-options.json`).option("--dry-run", "print the request this would send and send nothing").action(runAction(state, (client, opts) => {
 		const patch = {};
 		if (opts.name) patch.name = opts.name;
 		if (opts.required !== void 0) patch.required = opts.required;
@@ -11861,7 +12581,7 @@ Examples:
   busabase-cli bases create-change-request --base-id bse_123 --fields-json '{"title":"Hello","status":"draft"}'
   busabase-cli bases create-change-request --base-id bse_123 --fields-json @record.json
   busabase-cli bases create-change-request --base-id bse_123 --fields-json '{"title":"Hello"}' --auto-merge   # skip review, create immediately
-  busabase-cli bases create-change-request --base-id bse_123 --fields-json '{"title":"Hello"}' --require-review   # always propose a Change Request`).action(runAction(state, (client, opts) => client.bases.createChangeRequest({
+  busabase-cli bases create-change-request --base-id bse_123 --fields-json '{"title":"Hello"}' --require-review   # always propose a Change Request`).option("--dry-run", "print the request this would send and send nothing").action(runAction(state, (client, opts) => client.bases.createChangeRequest({
 		baseId: opts.baseId,
 		fields: parseJsonValue(opts.fieldsJson, "fields-json"),
 		message: opts.message,
@@ -11919,7 +12639,7 @@ Examples:
 Example:
   busabase-cli assets upload --file ./cover.png --output json
 
-Use the JSON output directly in an attachment field value, e.g. {"cover_image":[<output>]}.`).action(runAction(state, (_client, opts, config) => uploadAsset(config, opts)));
+Use the JSON output directly in an attachment field value, e.g. {"cover_image":[<output>]}.`).option("--dry-run", "print the request this would send and send nothing").action(runAction(state, (_client, opts, config) => uploadAsset(config, opts)));
 	const assetsCommand = program.command("assets").description("Assets");
 	addUploadCommand(assetsCommand);
 	addGlobalFlags(assetsCommand.command("put-text")).description("Write (or mark none) an asset's Drive Grep Retrieval text slot").requiredOption("--asset-id <id>", "asset id").option("--text <string>", "inline text (≤1MB)").option("--file <path>", "read text from a local file instead of --text").option("--none", "mark as having no extractable text (e.g. a scanned, image-only PDF)").addHelpText("after", `
@@ -12090,7 +12810,7 @@ Examples:
 
 To add content to a space that is already in use, use \`busabase-cli install\` instead.
 To copy a still-live space's current content into another space, use
-\`busabase-cli export\` + \`busabase-cli install\` instead of backup/restore.`).action(runArgAction(state, (file, client, opts, config) => runRestore(client, {
+\`busabase-cli export\` + \`busabase-cli install\` instead of backup/restore.`).option("--dry-run", "print the request this would send and send nothing").action(runArgAction(state, (file, client, opts, config) => runRestore(client, {
 		file,
 		resume: Boolean(opts.resume),
 		intoFolder: opts.intoFolder,
@@ -12101,7 +12821,7 @@ To copy a still-live space's current content into another space, use
 		"post",
 		"put",
 		"delete"
-	]).makeOptionMandatory()).requiredOption("--path <p>", "path under /api/v1, e.g. /bases").option("--query <k=v...>", "query-string param, repeatable").option("--body-json <json>", "JSON request body").action(runAction(state, (_client, opts, config) => {
+	]).makeOptionMandatory()).requiredOption("--path <p>", "path under /api/v1, e.g. /bases").option("--query <k=v...>", "query-string param, repeatable").option("--body-json <json>", "JSON request body").option("--dry-run", "print the request this would send and send nothing").action(runAction(state, (_client, opts, config) => {
 		const query = new URLSearchParams();
 		for (const pair of opts.query ?? []) {
 			const [key, ...rest] = pair.split("=");
@@ -12191,6 +12911,15 @@ async function runCli(argv) {
 			return EXIT_CODES.USAGE;
 		}
 		const classified = classifyError(error);
+		if (classified.code === "UNAUTHORIZED" || classified.code === "FORBIDDEN") {
+			const hintConfig = state.config ?? resolveConfig({});
+			const profile = isMultiProfile() ? activeCredentialTarget().profile : void 0;
+			const procedureId = state.procedureId ?? (state.lastRequest ? matchRoute(state.lastRequest.method, state.lastRequest.pathname)?.id : void 0);
+			classified.hint = authRecoveryHint(classified.code, hintConfig.baseUrl, profile, {
+				procedureId,
+				...procedureId ? requiredLevelFor(procedureId) : {}
+			});
+		}
 		if (json) console.log(JSON.stringify(errorEnvelope(classified), null, 2));
 		console.error(explainError(error, state.config ?? resolveConfig({})));
 		return classified.exitCode;