@vercel/board 0.24.0 → 0.25.1

package/dist/{main-CzWvRy91.mjs → main-DOhNCWMd.mjs}

@@ -1,14 +1,14 @@
 import { i as fileSize, n as DIRECT_UPLOAD_BYTES_MAX } from "./files-SniSmeEr.mjs";
 import { a as AttachmentId } from "./schemas-Be08nyfW.mjs";
-import { d as VERSION, i as withMentions } from "./watchers-hash-C_1jGA53.mjs";
+import { d as VERSION, i as withMentions } from "./watchers-hash-BHNXy_N7.mjs";
 import { n as displayEmoji, r as normalizeEmoji } from "./emoji-CTLpvH-A.mjs";
-import { t as BoardError } from "./client-ClznIBMg.mjs";
-import { i as groups, n as filters$1, o as options, r as globalOptions, s as usage, t as commands } from "./commands-BtL4jFq8.mjs";
-import { n as connect, s as vercelProjectFile, t as boardUrl } from "./node-CirFYqw0.mjs";
-import { t as http } from "./backend-http-tGUo0e8j.mjs";
-import { t as board } from "./server-Cp2oIQOj.mjs";
-import { t as conformance } from "./conformance-DQ9qVzWP.mjs";
-import { n as vercel, t as credentialSource } from "./backend-vercel-C3zuxmcD.mjs";
+import { t as BoardError } from "./client-D0Px7KzF.mjs";
+import { i as groups, n as filters$1, o as options, r as globalOptions, s as usage$1, t as commands } from "./commands-BtL4jFq8.mjs";
+import { n as connect, s as vercelProjectFile, t as boardUrl } from "./node-Bkd1x0QI.mjs";
+import { t as http } from "./backend-http-CJd4Fu0U.mjs";
+import { t as board } from "./server-BF4WJ7qi.mjs";
+import { t as conformance } from "./conformance-DlnfuzEB.mjs";
+import { n as vercel, t as credentialSource } from "./backend-vercel-Bqg2QfTd.mjs";
 import { t as displayText } from "./bots-CGkO76qH.mjs";
 import { spawn } from "node:child_process";
 import { readFile, stat, writeFile } from "node:fs/promises";
@@ -450,7 +450,7 @@ const flag = (option) => `${option.short ? `-${option.short}, ` : ""}--${option.
 const shown = (list) => list.filter((option) => !option.hidden);
 /** A command's rows in the list: itself, when it runs alone, and each of its subcommands. */
 function listed(command) {
-	return [...!command.subcommands || command.runsWithoutSubcommand ? [[usage([command]), command.description]] : [], ...(command.subcommands ?? []).filter((sub) => !sub.hidden).map((sub) => [usage([command, sub]), sub.description])];
+	return [...!command.subcommands || command.runsWithoutSubcommand ? [[usage$1([command]), command.description]] : [], ...(command.subcommands ?? []).filter((sub) => !sub.hidden).map((sub) => [usage$1([command, sub]), sub.description])];
 }
 /** Every command, by group, then what the app adds (`serve`, `inspect`), and the options they share. */
 function rootHelp(app, version) {
@@ -473,7 +473,7 @@ function commandHelp(name, path) {
 	const options = shown(command.options);
 	const subcommands = (command.subcommands ?? []).filter((sub) => !sub.hidden);
 	const lines = [
-		`usage: ${name} ${usage(path)}${options.length || command.filters ? " [options]" : ""}`,
+		`usage: ${name} ${usage$1(path)}${options.length || command.filters ? " [options]" : ""}`,
 		"",
 		...wrap(command.description, COLUMNS)
 	];
@@ -482,7 +482,7 @@ function commandHelp(name, path) {
 		if (entries.length) lines.push("", `${title}:`, ...rows(entries));
 	};
 	section("arguments", command.arguments.filter((argument) => argument.description).map((argument) => [argument.name, argument.description]));
-	section("commands", subcommands.map((sub) => [usage([...path, sub]), sub.description]));
+	section("commands", subcommands.map((sub) => [usage$1([...path, sub]), sub.description]));
 	section("options", options.map((option) => [flag(option), option.description]));
 	if (command.filters) {
 		section("filters", shown(filters$1).map((option) => [flag(option), option.description]));
@@ -508,8 +508,120 @@ function commandPath(words, all) {
 	return sub ? [command, sub] : [command];
 }
 //#endregion
+//#region src/cli/failure.ts
+function exitCode(failure) {
+	if (failure.class === "usage" || failure.class === "missing_input") return 2;
+	if (failure.class === "timeout") return 124;
+	if (failure.class === "canceled") return 130;
+	return 1;
+}
+/** An argument as a shell reads it back: bare when it's safe, quoted otherwise. A placeholder (`<TEAM>`) stays as it is. */
+const shellWord = (arg) => /^<[A-Z_]+>$/.test(arg) || /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+/** A recovery's command, as a person types it. */
+const commandLine = (argv) => argv.map(shellWord).join(" ");
+/**
+* The failure as lines, the headline first and the rest as they sit under it, before the indent a
+* CLI adds under its own mark (`error: `, `✗ `): details, context rows, then each way out after a
+* blank line, its command two spaces in.
+*/
+function failureLines(failure) {
+	const lines = [failure.message, ...failure.details ?? []];
+	for (const [label, value] of failure.context ?? []) lines.push(`${label.padEnd(14)}  ${value}`);
+	if (failure.next?.length) {
+		lines.push("");
+		for (const { instruction, argv } of failure.next) if (!argv) lines.push(instruction);
+		else lines.push(`${instruction}:`, `  ${commandLine(argv)}`);
+	}
+	return lines;
+}
+/** How board's own CLI prints it: `error: ` and the headline, the rest two spaces in. */
+function formatFailure(failure) {
+	return failureLines(failure).map((line, index) => index === 0 ? `error: ${line}` : line ? `  ${line}` : "").join("\n");
+}
+/**
+* The JSON error document `--json` prints on stderr, one line: each way out with a command in
+* `next`, and the ones that are only words in `hint`.
+*/
+function failureDocument(failure) {
+	const next = (failure.next ?? []).flatMap(({ instruction, argv }) => argv ? [{
+		command: commandLine(argv),
+		argv,
+		when: instruction
+	}] : []);
+	const hint = (failure.next ?? []).flatMap(({ instruction, argv }) => argv ? [] : [instruction]);
+	return {
+		status: failure.actionRequired ? "action_required" : "error",
+		reason: failure.reason,
+		message: failure.message,
+		...next.length ? { next } : {},
+		...hint.length ? { hint: hint.join(" ") } : {},
+		...failure.data ? { data: failure.data } : {}
+	};
+}
+/**
+* The closest of `known` to `word`, when it's a likely typo: one edit away (a letter added, dropped,
+* changed, or two swapped), or two for a word of six letters or more.
+*/
+function closest(word, known) {
+	let best;
+	let distance = Infinity;
+	for (const candidate of known) {
+		const d = edits(word.toLowerCase(), candidate.toLowerCase());
+		if (d < distance) [best, distance] = [candidate, d];
+	}
+	return best !== void 0 && distance > 0 && distance <= (word.length >= 6 ? 2 : 1) ? best : void 0;
+}
+/** How many edits turn `a` into `b`, a swap of neighbors counting as one. */
+function edits(a, b) {
+	const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => i === 0 ? j : j === 0 ? i : 0));
+	for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
+		d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+		if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+	}
+	return d[a.length][b.length];
+}
+//#endregion
 //#region src/cli/main.ts
-var UsageError = class extends Error {};
+/** A failure this run says in its own words: what a command throws to stop with it. */
+var Failed = class extends Error {
+	failure;
+	constructor(failure) {
+		super(failure.message);
+		this.failure = failure;
+	}
+};
+/**
+* Misuse: `message` says what's wrong with the command as typed. It exits 2, and points at the
+* command's help unless `next` says something better.
+*/
+function usage(message, options = {}) {
+	return new Failed({
+		class: "usage",
+		reason: options.reason ?? "invalid_arguments",
+		message,
+		next: options.next ?? [helpRecovery()]
+	});
+}
+/** A command's help page, which says how to use it. */
+const helpRecovery = (command = current.command) => ({
+	instruction: "See how to use it",
+	argv: [
+		...cli(),
+		...command ? [command] : [],
+		"--help"
+	]
+});
+/** This CLI's name as argv, to build a command a person runs: `['vb']`, `['vercel', 'board']`. */
+const cli = () => named().split(" ");
+/** This run's command as typed, with `extra` where options go: before any `--`, after which everything is text. */
+function rerun(...extra) {
+	const at = typed.indexOf("--");
+	return [...cli(), ...at === -1 ? [...typed, ...extra] : [
+		...typed.slice(0, at),
+		...extra,
+		...typed.slice(at)
+	]];
+}
 /** What the parser accepts: every option, by name (`commands.ts`). */
 const OPTIONS = options;
 /** Options by their short letter: `n` is `limit`. */
@@ -550,14 +662,43 @@ function markAttachmentId(args) {
 }
 /** Commands that are gone, and what to run instead. Their flags don't matter: an old hook's `vb update --skip` gets this too. */
 function removedCommand(word) {
-	const cli = named();
+	const gone = (next, why = "") => usage(`\`${named()} ${word}\` is gone.${why}`, {
+		reason: "unknown_command",
+		next
+	});
+	const url = [{
+		instruction: "Pass the board's URL",
+		argv: [
+			...cli(),
+			"read",
+			"dev",
+			"--url",
+			"<URL>"
+		]
+	}, { instruction: "Or, in a Vercel project, its team's board needs no URL" }];
 	const removed = {
-		update: `\`${cli} update\` is gone: reply in the thread you're working in (${cli} reply <id>), or post where it fits (${cli} post <channel>)`,
-		stuck: `\`${cli} stuck\` is gone: a board on a2() keeps its dead letters in A2, on the backend's \`servers\``,
-		link: `\`${cli} link\` is gone: pass --url <url> (or set BOARD_URL), and in a Vercel project its team's board needs neither`,
-		use: `\`${cli} use\` is gone: pass --url <url> (or set BOARD_URL), and in a Vercel project its team's board needs neither`
+		update: () => gone([{
+			instruction: "Reply in the thread you're working in",
+			argv: [
+				...cli(),
+				"reply",
+				"<ID>",
+				"<TEXT>"
+			]
+		}, {
+			instruction: "Or post where it fits",
+			argv: [
+				...cli(),
+				"post",
+				"<CHANNEL>",
+				"<TEXT>"
+			]
+		}]),
+		stuck: () => gone([], " A board on a2() keeps its dead letters in A2, on the backend's `servers`."),
+		link: () => gone(url),
+		use: () => gone(url)
 	};
-	return Object.hasOwn(removed, word) ? removed[word] : void 0;
+	return Object.hasOwn(removed, word) ? removed[word]() : void 0;
 }
 /**
 * The command `argv` runs, by its own name (`delete` for `rm`), as the parser reads it: the
@@ -584,6 +725,17 @@ let app = {
 };
 let flags = {};
 let positionals = [];
+/** The command this run runs, by its own name, and what follows it: what a failure says it was doing. */
+let current = {
+	command: void 0,
+	args: []
+};
+/** What this run was given, as typed: what a recovery runs again, with what it lacked. */
+let typed = [];
+/** What this run's writes had to say, for its JSON result. */
+let warnings = [];
+/** The board this run reached by its URL, for a failure to name. */
+let reached = null;
 /** The help `words` ask for: a command's page when they name one (`read`, `identity link`), or else every command. */
 function help(words = []) {
 	const own = Object.values(app.commands).map((command) => command.spec);
@@ -595,43 +747,115 @@ function help(words = []) {
 }
 /** How messages name this CLI: `vb` for the standalone one, as they always have, or the app's own name. */
 const named = () => app.name === "board" ? "vb" : app.name;
-/** Parses `argv` for this run: false, once the error line is out, when it doesn't. */
+/** The commands that take their text as an argument, where text that starts with `-` goes after `--`. */
+const TEXT = /* @__PURE__ */ new Set([
+	"post",
+	"reply",
+	"edit",
+	"schedule"
+]);
+/** Parses `argv` for this run, or throws what's wrong with it. */
 function parse(argv) {
 	const args = withMentions(argv);
-	const removed = removedCommand(commandWord(args) ?? "");
+	const word = commandWord(args);
+	current = {
+		command: word,
+		args: []
+	};
+	const removed = removedCommand(word ?? "");
+	if (removed) throw removed;
 	try {
-		if (removed) throw new UsageError(removed);
 		const parsed = parseAll(markAttachmentId(args));
 		flags = parsed.values;
 		positionals = parsed.positionals.map((arg) => arg.startsWith(MARK) ? arg.slice(1) : arg);
-		return true;
 	} catch (error) {
-		const unknown = error.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" && /'([^']+)'/.exec(error.message)?.[1];
-		io.error(terminalText(`error: ${unknown ? `unknown option: ${unknown} (run \`${app.name} help\`; text starting with - goes after --, as in -- "${unknown}")` : error.message}`) + "\n");
-		return false;
+		throw parseFailure(error, argv, word);
 	}
 }
+/** What the parser rejected, as misuse: an unknown option (with the likeliest one meant), or an option without its value. */
+function parseFailure(error, argv, word) {
+	const option = error.message.match(/--[a-z][\w-]*/)?.[0] ?? /'(-[^' ,]+)/.exec(error.message)?.[1];
+	if (error.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" && option) {
+		const guess = option.startsWith("--") ? closest(option.slice(2), optionsOf(word)) : void 0;
+		const next = [{
+			instruction: "See all options",
+			argv: [
+				...cli(),
+				...word ? [word] : [],
+				"--help"
+			]
+		}];
+		const at = argv.indexOf(option);
+		if (word && TEXT.has(word) && at !== -1) {
+			const rest = [...argv.slice(0, at), ...argv.slice(at + 1)];
+			const dash = rest.indexOf("--");
+			const text = dash === -1 ? [
+				...rest,
+				"--",
+				option
+			] : [
+				...rest.slice(0, dash + 1),
+				option,
+				...rest.slice(dash + 1)
+			];
+			next.push({
+				instruction: "Or, for text that starts with -, put it after --",
+				argv: [...cli(), ...text]
+			});
+		}
+		return usage(`Unknown option ${option} for ${`${named()}${word ? ` ${word}` : ""}`}.${guess ? ` Did you mean --${guess}?` : ""}`, {
+			reason: "unknown_option",
+			next
+		});
+	}
+	if (error.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE" && option) return usage(`${option} needs a value.`, { reason: "missing_value" });
+	return usage(sentence(error.message));
+}
+/** The options `word`'s command takes, its subcommands' and the filters included, and the ones every command takes. */
+function optionsOf(word) {
+	const command = [...commands, ...Object.values(app.commands).map((own) => own.spec)].find((known) => known.name === word);
+	return [...command ? [command, ...command.subcommands ?? []].flatMap((c) => [...c.options, ...c.filters ? filters$1 : []]) : [], ...globalOptions].map((option) => option.name);
+}
+/** `text` as a sentence: a capital first, and a period last. */
+const sentence = (text) => {
+	const trimmed = text.trim();
+	return `${trimmed.charAt(0).toUpperCase()}${trimmed.slice(1)}${/[.!?]$/.test(trimmed) ? "" : "."}`;
+};
 const TERMINAL = {
 	write: (chunk) => void process.stdout.write(chunk),
 	error: (chunk) => void process.stderr.write(chunk),
 	async readFile(path) {
 		const info = await stat(path).catch(() => null);
 		if (!info?.isFile()) return null;
-		if (info.size > 104857600) throw new UsageError(`${path} is over ${DIRECT_UPLOAD_BYTES_MAX / 1024 / 1024} MB, the most an attachment can be`);
+		if (info.size > 104857600) throw tooLarge(path);
 		return new Uint8Array(await readFile(path));
 	},
 	writeFile: (path, data) => writeFile(path, data),
-	stdin: readStdin
+	stdin: readStdin,
+	tty: process.stdout.isTTY === true
 };
 let io = TERMINAL;
 const out = (text) => io.write(`${terminalText(text)}\n`);
-const printJson = (value) => io.write(`${JSON.stringify(value)}\n`);
+/** `--json`'s result: one document, with what the run's writes warned about, indented at a terminal. */
+const result = (value) => io.write(`${JSON.stringify(warnings.length ? {
+	...value,
+	warnings
+} : value, null, io.tty ? 2 : void 0)}\n`);
+/** One line of a JSON stream (`tail`, `identity link`): compact, wherever it goes. */
+const line = (value) => io.write(`${JSON.stringify(value)}\n`);
 /** A message's ID as you'd write it: `#812` or `812`. It's passed to the board as it is. */
-function messageId(value, what = "message id") {
+function messageId(value, what = "message ID") {
 	const id = value?.replace(/^#/, "") ?? "";
-	if (!/^[^\s/]+$/.test(id)) throw new UsageError(`expected a ${what}, got: ${value ?? "(nothing)"}`);
+	if (value === void 0) throw usage(`Missing the ${what}.`, { reason: "missing_arguments" });
+	if (!/^[^\s/]+$/.test(id)) throw usage(`${value} isn't a ${what}.`);
 	return id;
 }
+/** A file over what a direct upload takes. */
+const tooLarge = (path) => new Failed({
+	class: "limit",
+	reason: "payload_too_large",
+	message: `Can't attach ${path}. It's over ${DIRECT_UPLOAD_BYTES_MAX / 1024 / 1024} MB, the most an attachment can be.`
+});
 /** Whether an argument names a message rather than a channel: `#<id>`, or a bare number. */
 const isMessageRef = (value) => /^#[^\s/]+$/.test(value) || /^\d+$/.test(value);
 /** A message's ID as it's passed back: bare when it's a number, `#<id>` when it could be a channel's name. */
@@ -640,13 +864,13 @@ function labelPairs(values) {
 	const pairs = {};
 	for (const value of values ?? []) {
 		const at = value.indexOf("=");
-		if (at <= 0) throw new UsageError(`labels look like key=value, got: ${value}`);
+		if (at <= 0) throw usage(`Labels look like key=value, and ${value} isn't one.`);
 		pairs[value.slice(0, at)] = value.slice(at + 1);
 	}
 	return pairs;
 }
 async function text(value) {
-	if (value === void 0) throw new UsageError("missing message text");
+	if (value === void 0) throw usage("Missing the message's text: pass it, or - to read it from stdin.", { reason: "missing_arguments" });
 	if (value !== "-") return value;
 	return (await io.stdin()).replace(/\n$/, "");
 }
@@ -655,8 +879,11 @@ async function attachments(board) {
 	const files = [];
 	for (const path of flags.attach ?? []) {
 		const data = await io.readFile(path);
-		if (!data) throw new UsageError(`no such file: ${path}`);
-		if (data.byteLength > 104857600) throw new UsageError(`${path} is over ${DIRECT_UPLOAD_BYTES_MAX / 1024 / 1024} MB, the most an attachment can be`);
+		if (!data) throw usage(`Can't attach ${path}. There's no such file.`, {
+			reason: "file_not_found",
+			next: []
+		});
+		if (data.byteLength > 104857600) throw tooLarge(path);
 		files.push({
 			path,
 			data
@@ -672,13 +899,14 @@ async function attachments(board) {
 /** `s12` or `12`. */
 function scheduleId(value) {
 	const id = value?.replace(/^s(?=\d)/i, "") ?? "";
-	if (!/^[^\s/]+$/.test(id)) throw new UsageError(`expected a schedule id like s12, got: ${value ?? "(nothing)"}`);
+	if (value === void 0) throw usage("Missing the schedule ID, like s12.", { reason: "missing_arguments" });
+	if (!/^[^\s/]+$/.test(id)) throw usage(`${value} isn't a schedule ID like s12.`);
 	return id;
 }
 /** A time flag: anything `Date` reads, as ISO. */
 function instant(flag, value) {
 	const time = new Date(value);
-	if (Number.isNaN(time.getTime())) throw new UsageError(`--${flag} takes a time like 2026-10-08T09:00:00Z, got: ${value}`);
+	if (Number.isNaN(time.getTime())) throw usage(`--${flag} takes a time like 2026-10-08T09:00:00Z, and ${value} isn't one.`);
 	return time.toISOString();
 }
 function filters(channel) {
@@ -703,14 +931,205 @@ function configuredUrl() {
 	} catch (error) {
 		if (!(error instanceof BoardError) || error.code !== "no_board") throw error;
 		if (app.teamBoard || process.env.VERCEL_ORG_ID || vercelProjectFile()) return null;
-		const ways = [
-			"pass --url <url> (or set BOARD_URL)",
-			"--scope <team> for a team's board in Vercel's API",
-			"run it in a Vercel project (vercel link) for its team's",
-			...app.commands.serve ? [`\`${named()} serve\` for a local one`] : []
-		];
-		throw new BoardError("no_board", `no board: ${ways.slice(0, -1).join(", ")}, or ${ways.at(-1)}`, 0);
+		throw new Failed({
+			class: "missing_input",
+			reason: "missing_scope",
+			actionRequired: true,
+			message: "No board to use. Nothing sets one, and this directory isn't in a Vercel project.",
+			next: [{
+				instruction: "Use a team's board",
+				argv: rerun("--scope", "<TEAM>")
+			}, {
+				instruction: "Or a board at a URL",
+				argv: rerun("--url", "<URL>")
+			}]
+		});
+	}
+}
+/** A board that predates what this run asked of it. */
+const outdated = (message) => new Failed({
+	class: "platform",
+	reason: "board_outdated",
+	message: `${message} It's older than this CLI.`,
+	next: [{ instruction: "Update @vercel/board where the board is deployed" }]
+});
+/** A message ID as a failure names it: `#812`. */
+const ref = (value) => value === void 0 ? "a message" : `#${value.replace(/^#/, "")}`;
+/** What this run was doing, as a failure's headline says it: `post to dev`, `reply to #812`. */
+function doing() {
+	const { command, args } = current;
+	const [a, b, c] = args;
+	const message = a !== void 0 && isMessageRef(a);
+	switch (command) {
+		case "read": return a === void 0 ? "read the board" : /^https?:\/\//i.test(a) ? "read that link" : `read ${message ? ref(a) : a}`;
+		case "post": return message ? `reply to ${ref(a)}` : `post to ${a ?? "a channel"}`;
+		case "reply": return `reply to ${ref(a)}`;
+		case "edit":
+		case "delete":
+		case "label": return `${command} ${ref(a)}`;
+		case "react": return `react to ${ref(a)}`;
+		case "typing": return `show typing in ${ref(a)}`;
+		case "sync": return b === void 0 ? `list where ${ref(a)} is synced` : `sync ${ref(a)} with ${b}`;
+		case "schedule": return a === "cancel" ? `cancel schedule ${b}` : `schedule a message in ${message ? ref(a) : a ?? "a channel"}`;
+		case "schedules":
+		case "channels":
+		case "actors": return `list ${command}`;
+		case "sources": return b === void 0 ? "list sources" : `${b} ${c ?? "it"} on ${a}`;
+		case "identity": return a === "link" ? `link your account on ${b}` : a === "unlink" ? `unlink ${b}` : "list your linked accounts";
+		case "download": return `download ${a ?? "the attachment"}`;
+		case "inbox": return `read ${a}'s inbox`;
+		case "tail": return `follow ${a ?? "the board"}`;
+		case "wait": return `wait on ${a ?? "the board"}`;
+		case "whoami": return "reach the board";
+		case "conformance": return "check the board";
+		default: return `run ${named()}${command ? ` ${command}` : ""}`;
+	}
+}
+/** The commands whose first argument is always a message. */
+const ON_MESSAGE = /* @__PURE__ */ new Set([
+	"reply",
+	"edit",
+	"delete",
+	"react",
+	"label",
+	"typing",
+	"sync",
+	"schedules"
+]);
+/** What a 404 means this run couldn't find, when its arguments name it: `message #812`. */
+function missing() {
+	const { command = "", args } = current;
+	const [a, b] = args;
+	if (a === void 0) return void 0;
+	if (command === "read" && /^https?:\/\//i.test(a)) return "that link's message on this board";
+	if (ON_MESSAGE.has(command) || [
+		"read",
+		"post",
+		"schedule"
+	].includes(command) && isMessageRef(a)) return `message ${ref(a)}`;
+	if (command === "schedule" && a === "cancel" && b !== void 0) return `schedule ${b}`;
+	if (command === "download") return `attachment ${a}`;
+}
+/**
+* What `error` means for this run, in the Vercel CLI's terms. What the handle raised itself says
+* what and why, and its hint what fixes it. What a board answered is said by what this run was
+* doing, with the board's words under it and in `data`, never in what to run: a board can answer
+* with any code, the handle's own included.
+*/
+function failureOf(error) {
+	if (error instanceof Failed) return error.failure;
+	const message = error instanceof Error ? error.message : String(error);
+	const { code, status, hint, origin } = error;
+	if (typeof code !== "string" || typeof status !== "number") return {
+		class: "unknown",
+		reason: "unexpected_error",
+		message: `Failed to ${doing()}.`,
+		details: [message]
+	};
+	const said = { error: {
+		code,
+		message,
+		status,
+		...typeof hint === "string" ? { hint } : {}
+	} };
+	if (origin === "handle") {
+		const fix = typeof hint === "string" ? [{ instruction: hint }] : [];
+		const own = (kind, reason, next = fix) => ({
+			class: kind,
+			reason,
+			message,
+			...next.length ? { next } : {},
+			data: said
+		});
+		switch (code) {
+			case "not_logged_in": return {
+				class: "auth",
+				reason: "login_required",
+				message: "You're not logged in to Vercel.",
+				next: [{
+					instruction: "Log in",
+					argv: ["vercel", "login"]
+				}],
+				data: said
+			};
+			case "no_access": return own("permission", "permission_denied");
+			case "wrong_project": return own("permission", "wrong_project");
+			case "protected": return own("permission", "deployment_protected");
+			case "no_project": return own("platform", "no_project");
+			case "no_token": return own("auth", "token_unavailable");
+			case "no_board": return own("not_found", "board_not_found");
+			case "too_many_redirects": return own("network", "network_error");
+			case "invalid_duration": return own("usage", "invalid_arguments", [helpRecovery()]);
+			case "wrong_audience":
+			case "redirected": return own("usage", "wrong_url");
+			case "ambiguous_agent": return own("usage", "ambiguous_agent", [{
+				instruction: "Write as one of them",
+				argv: rerun("--as", "<PROFILE>")
+			}, {
+				instruction: "Or as yourself",
+				argv: rerun("--human")
+			}]);
+			case "too_large": return {
+				...own("limit", "payload_too_large"),
+				message: `Can't ${doing()}. ${sentence(message)}`
+			};
+			case "upload_failed": return {
+				...own("platform", "upload_failed"),
+				message: `Failed to ${doing()}.`,
+				details: [message]
+			};
+			case "port_taken": return own("conflict", "port_taken", [{
+				instruction: "Pick another port",
+				argv: [
+					...cli(),
+					current.command ?? "serve",
+					"--port",
+					"<PORT>"
+				]
+			}]);
+		}
+	}
+	const theirs = (kind, reason, headline, next = []) => ({
+		class: kind,
+		reason,
+		message: headline,
+		details: [message],
+		...reached && [
+			"auth",
+			"permission",
+			"network",
+			"platform"
+		].includes(kind) ? { context: [["Board", reached]] } : {},
+		...next.length ? { next } : {},
+		data: said
+	});
+	const specific = (fallback) => /^[a-z]+(_[a-z]+)+$/.test(code) && code !== "invalid_request" && code !== "remote_error" ? code : fallback;
+	if (status === 400) return theirs("usage", specific("invalid_arguments"), `Can't ${doing()}.`);
+	if (status === 401) return theirs("auth", "login_required", "The board didn't accept your credentials.", [{
+		instruction: "Log in again",
+		argv: ["vercel", "login"]
+	}]);
+	if (status === 403) return theirs("permission", "permission_denied", `You can't ${doing()}.`);
+	if (status === 404) {
+		const thing = missing();
+		return thing ? {
+			...theirs("not_found", specific("not_found"), `Couldn't find ${thing}.`),
+			details: []
+		} : theirs("not_found", specific("not_found"), `Can't ${doing()}.`);
 	}
+	if (status === 409) return theirs("conflict", specific("conflict"), `Can't ${doing()}.`);
+	if (status === 413) return theirs("limit", "payload_too_large", `Can't ${doing()}. It's too large for the board.`);
+	if (status === 429) return theirs("rate_limit", "rate_limited", "Too many requests to the board. Try again in a minute.");
+	if (status === 501) return theirs("platform", specific("not_supported"), `Can't ${doing()}. This board doesn't support it.`);
+	if (code === "unreachable") return theirs("network", "network_error", "Couldn't reach the board.");
+	return theirs("platform", "api_error", `Failed to ${doing()}.`);
+}
+/** How this run ends with `failure`: shown on stderr, or by the app, and its exit code. */
+function report(failure, json) {
+	if (app.onError) app.onError(failure, { json });
+	else if (json) io.error(`${JSON.stringify(failureDocument(failure))}\n`);
+	else io.error(`${terminalText(formatFailure(failure))}\n`);
+	return exitCode(failure);
 }
 /**
 * A team's board in Vercel's API, by the URL its discovery names it with
@@ -759,6 +1178,7 @@ function connection(url = flags.url, options = {}) {
 		};
 	}
 	const at = configured.replace(/\/+$/, "");
+	reached = at;
 	const onVercel = vercelBoard(at);
 	if (onVercel) {
 		const board$3 = board({ backend: vercel(onVercel) });
@@ -797,24 +1217,40 @@ async function readStdin() {
 }
 function hookAgents(names) {
 	const known = Object.keys(AGENTS);
-	for (const name of names) if (!known.includes(name)) throw new UsageError(`unknown agent: ${name} (known: ${known.join(", ")})`);
+	for (const name of names) if (!known.includes(name)) throw usage(`Unknown agent ${name}. The agents are ${known.join(", ")}.`);
 	return names.length ? names : known;
 }
+/** Says what a write that went through had to say: in its JSON result with `--json`, on stderr otherwise. */
+function warn(warning) {
+	if (flags.json) warnings.push(warning);
+	else if (app.onWarning) app.onWarning(warning);
+	else io.error(`${terminalText(`warning: ${warning.message}`)}\n`);
+}
 /** A write went through, but some handles in it matched no one: they stayed plain text. */
 function warnUnknownMentions(handles) {
 	if (!handles?.length) return;
 	const names = handles.map((handle) => `@${handle}`);
 	const list = names.length === 1 ? names[0] : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
 	const one = names.length === 1;
-	io.error(terminalText(`warning: ${list} ${one ? "matches" : "match"} no one on the board, so ${one ? "it stays" : "they stay"} plain text and ${one ? "notifies" : "notify"} no one`) + "\n");
+	warn({
+		reason: "unknown_mention",
+		message: `${list} ${one ? "matches" : "match"} no one on the board, so ${one ? "it stays" : "they stay"} plain text and ${one ? "notifies" : "notify"} no one.`
+	});
 }
+/** A post or reply: its ID, or with `--json`, the message. */
 function printMessage(message) {
-	if (flags.json) printJson(message);
+	if (flags.json) result({
+		message,
+		outcome: "posted"
+	});
 	else out(messageRef(message.id));
 }
-function printEvent(event) {
-	if (flags.json) printJson(event);
-	else out(formatEvent(event));
+/** A write that answers nothing but that it went through: with `--json`, which message, and what happened to it. */
+function printDone(id, outcome) {
+	if (flags.json) result({
+		message: { id },
+		outcome
+	});
 }
 /** Best-effort: the URL is printed either way. */
 /** `url`, when it's an http or https URL as `new URL` reads it: the only kind the CLI opens, so a board can't hand the opener a flag or another scheme. */
@@ -844,7 +1280,7 @@ function openBrowser(url) {
 }
 function portFlag() {
 	const port = flags.port === void 0 ? void 0 : Number(flags.port);
-	if (port !== void 0 && !(Number.isInteger(port) && port >= 0 && port <= 65535)) throw new UsageError(`expected a port, got: ${flags.port}`);
+	if (port !== void 0 && !(Number.isInteger(port) && port >= 0 && port <= 65535)) throw usage(`${flags.port} isn't a port.`, { reason: "invalid_port" });
 	return port;
 }
 /** How long `identity link` waits for the sign-in or the code. */
@@ -854,26 +1290,39 @@ async function identity(args) {
 	const [sub, target] = args;
 	if (sub === void 0) {
 		const view = await board.identity();
-		if (flags.json) return printJson(view), 0;
+		if (flags.json) return result(view), 0;
 		if (view.links.length === 0) out("no linked accounts");
 		for (const link of view.links) out(`${link.handle ? `@${link.handle}  ` : ""}${link.actor}  by ${link.method === "code" ? "code" : "sign-in"} · ${link.at}`);
 		if (view.unlinked?.length) out(`not linked  ${view.unlinked.join(", ")}  (${named()} identity link <key>)`);
 		return 0;
 	}
 	if (sub === "unlink") {
-		if (!target || args.length !== 2) throw new UsageError(`usage: ${app.name} identity unlink <account>   (a handle or actor ID from \`${app.name} identity\`)`);
-		const result = await board.unlinkAccount(target);
-		if (flags.json) printJson(result);
-		else out(`unlinked ${result.actor}`);
+		if (!target) throw usage(`Missing the account to unlink: a handle or actor ID from \`${named()} identity\`.`, { reason: "missing_arguments" });
+		if (args.length !== 2) throw usage("identity unlink takes one account.");
+		const unlinked = await board.unlinkAccount(target);
+		if (flags.json) result({
+			...unlinked,
+			outcome: "unlinked"
+		});
+		else out(`unlinked ${unlinked.actor}`);
 		return 0;
 	}
-	if (sub !== "link" || !target || args.length !== 2) throw new UsageError(`usage: ${app.name} identity [link <key> [--code] [--no-wait] | unlink <account>]`);
+	if (sub !== "link") throw usage(`Unknown command ${sub} for ${named()} identity.`, { reason: "unknown_command" });
+	if (!target) throw usage("Missing the sync entry to link your account on, such as slack.", { reason: "missing_arguments" });
+	if (args.length !== 2) throw usage("identity link takes one sync entry.");
 	const before = new Set((await board.identity()).links.map((link) => `${link.actor}|${link.at}`));
 	const platform = (await board.discovery().catch(() => null))?.sync.find((entry) => entry.key === target)?.platform ?? target;
 	const { code, expiresAt, signIn } = await board.syncCode(target);
 	const consent = signIn !== void 0 && !flags.code;
-	if (consent && browsable(signIn) === null) throw new Error(`the board's sign-in isn't an http or https URL: ${JSON.stringify(signIn)}`);
-	if (flags.json) printJson({
+	if (consent && browsable(signIn) === null) throw new Failed({
+		class: "platform",
+		reason: "invalid_sign_in",
+		message: "The board's sign-in isn't an http or https URL.",
+		details: [JSON.stringify(signIn)],
+		data: { signIn }
+	});
+	if (flags.json) line({
+		type: "code",
 		sync: target,
 		platform,
 		code,
@@ -899,13 +1348,28 @@ async function identity(args) {
 		await sleep();
 		const linked = await linkedSince();
 		if (linked) {
-			if (flags.json) printJson(linked);
+			if (flags.json) line({
+				type: "linked",
+				account: linked
+			});
 			else out(`linked ${linked.handle ? `@${linked.handle} ` : ""}(${linked.actor})`);
 			return 0;
 		}
 	}
-	io.error("timed out\n");
-	return 124;
+	throw new Failed({
+		class: "timeout",
+		reason: "timeout",
+		message: consent ? "Nothing linked an account within 10 minutes." : "The code expired before a message carried it.",
+		next: [{
+			instruction: "Try again",
+			argv: [
+				...cli(),
+				"identity",
+				"link",
+				target
+			]
+		}]
+	});
 }
 async function run(command, args) {
 	switch (command) {
@@ -919,7 +1383,7 @@ async function run(command, args) {
 			const url = given ?? discovered.url;
 			const source = transport.source();
 			if (flags.json) {
-				printJson({
+				result({
 					...me,
 					board: url,
 					source
@@ -941,15 +1405,15 @@ async function run(command, args) {
 			return 0;
 		}
 		case "conformance": {
-			if (args.length > 0) throw new UsageError(`usage: ${app.name} conformance [--channel <c>]`);
+			if (args.length > 0) throw usage("conformance takes no arguments: pass its channel with --channel.");
 			const report = await conformance(client(), flags.channel ? { channel: flags.channel } : {});
-			if (flags.json) printJson(report);
+			if (flags.json) result(report);
 			else out(formatConformance(report));
 			return report.ok ? 0 : 1;
 		}
 		case "channels": {
 			const channels = await client().channels();
-			if (flags.json) return channels.forEach(printJson), 0;
+			if (flags.json) return result({ channels }), 0;
 			if (channels.length === 0) return out("no channels yet"), 0;
 			let group = "";
 			for (const channel of channels) {
@@ -965,7 +1429,7 @@ async function run(command, args) {
 		}
 		case "actors": {
 			const actors = await client().actors();
-			if (flags.json) return actors.forEach(printJson), 0;
+			if (flags.json) return result({ actors }), 0;
 			for (const actor of actors) out(`@${actor.handle}  ${actor.name}  ${actor.id}${actor.person ? `  → @${actor.person.handle}` : ""}`);
 			return 0;
 		}
@@ -976,14 +1440,17 @@ async function run(command, args) {
 			const link = target !== void 0 && /^https?:\/\//i.test(target);
 			if (target && (link || isMessageRef(target))) {
 				const thread = link ? await board.linked(target) : await board.thread(messageId(target));
-				if (link && !Array.isArray(thread.replies)) throw new Error("this board can't read links: update board where the board is deployed");
+				if (link && !Array.isArray(thread.replies)) throw outdated("This board can't read links.");
 				const narrowed = Object.keys(filters()).length > 0;
 				const replies = narrowed ? (await board.messages({
 					...filters(),
 					re: thread.message.id,
 					limit: 500
 				})).messages.filter((m) => m.re !== null) : thread.replies;
-				if (flags.json) return [thread.message, ...replies].forEach(printJson), 0;
+				if (flags.json) return result({
+					...thread,
+					replies
+				}), 0;
 				const authors = new Set([thread.message, ...replies].map((m) => m.by.actor));
 				const unnamed = reactionNames([thread.message, ...replies]).filter((id) => !authors.has(id));
 				const known = unnamed.length ? new Map((await board.actors().catch(() => [])).filter((a) => unnamed.includes(a.id)).map((a) => [a.id, actorName(a)])) : /* @__PURE__ */ new Map();
@@ -995,13 +1462,27 @@ async function run(command, args) {
 				...filters(target),
 				...flags.limit ? { limit: Number(flags.limit) } : {}
 			};
-			const old = /* @__PURE__ */ new Error("this board can't list threads: update board where the board is deployed");
+			const old = outdated("This board can't list threads.");
 			const page = await board.threads(query).catch((error) => {
-				throw error instanceof BoardError && error.status === 404 ? old : error;
+				throw error instanceof BoardError && error.status === 404 && /^no route: /.test(error.message) ? old : error;
 			});
 			if (!Array.isArray(page.threads)) throw old;
-			if (!page.threads.length && target && !(await board.channels()).some((c) => c.path === target || c.path.startsWith(target.replace(/\/?$/, "/")))) throw new Error(`no channel ${target}: board channels lists them`);
-			if (flags.json) return page.threads.forEach(printJson), 0;
+			if (!page.threads.length && target) {
+				const channels = (await board.channels()).map((c) => c.path);
+				if (!channels.some((path) => path === target || path.startsWith(target.replace(/\/?$/, "/")))) {
+					const guess = closest(target, channels);
+					throw new Failed({
+						class: "not_found",
+						reason: "channel_not_found",
+						message: `Couldn't find channel ${target}.${guess ? ` Did you mean ${guess}?` : ""}`,
+						next: [{
+							instruction: "See its channels",
+							argv: [...cli(), "channels"]
+						}]
+					});
+				}
+			}
+			if (flags.json) return result(page), 0;
 			const count = `${page.threads.length} ${page.threads.length === 1 ? "thread" : "threads"}`;
 			out(`${target ?? "all channels"} · ${count} · cursor ${page.cursor}${page.threads.length ? "\n" : ""}`);
 			if (page.threads.length) out(formatThreadSummaries(page.threads, { channel: !target || target.endsWith("/") }));
@@ -1009,10 +1490,18 @@ async function run(command, args) {
 		}
 		case "post": {
 			const [target, body] = args;
-			if (!target) throw new UsageError(`usage: ${app.name} post <channel|id> "<text>"`);
+			if (!target) throw usage("Missing the channel or message to post to.", { reason: "missing_arguments" });
 			const re = isMessageRef(target) ? messageId(target) : void 0;
-			if (re !== void 0 && flags.sync?.length) throw new UsageError(`--sync attaches whole threads: post to a channel, or use ${named()} sync <id> <target>`);
-			if (flags.sync?.length && flags["no-sync"]) throw new UsageError("--sync and --no-sync contradict each other");
+			if (re !== void 0 && flags.sync?.length) throw usage("Can't use --sync on a reply. It syncs whole threads.", { next: [{
+				instruction: "Sync the thread instead",
+				argv: [
+					...cli(),
+					"sync",
+					re,
+					"<TARGET>"
+				]
+			}] });
+			if (flags.sync?.length && flags["no-sync"]) throw usage("Can't use --sync with --no-sync.");
 			const board = client();
 			const content = body === void 0 && flags.attach?.length ? "" : await text(body);
 			const files = await attachments(board);
@@ -1049,16 +1538,19 @@ async function run(command, args) {
 		case "schedule": {
 			if (args[0] === "cancel" && args.length === 2) {
 				const { schedule, canceled } = await client().cancelSchedule(scheduleId(args[1]));
-				if (flags.json) printJson(schedule);
+				if (flags.json) result({
+					schedule,
+					outcome: canceled ? "canceled" : "unchanged"
+				});
 				else out(canceled ? `canceled s${schedule.id}` : `s${schedule.id} is already ${schedule.state}`);
 				return 0;
 			}
 			const [target, body] = args;
-			if (!target) throw new UsageError(`usage: ${app.name} schedule <channel|id> "<text>" (--in 1d | --at <time> | --every 30m)`);
-			if (!flags.in && !flags.at && !flags.every) throw new UsageError("say when: --in 1d, --at <time>, or --every 30m");
-			if (flags.sync?.length) throw new UsageError("a schedule posts where you point it: --sync is for post");
+			if (!target) throw usage("Missing the channel or message to schedule a message in.", { reason: "missing_arguments" });
+			if (!flags.in && !flags.at && !flags.every) throw usage("Can't schedule a message without a time: pass --in 1d, --at <time>, or --every 30m.", { reason: "missing_arguments" });
+			if (flags.sync?.length) throw usage("Can't use --sync with schedule. A schedule posts where you point it.");
 			const times = flags.times === void 0 ? void 0 : Number(flags.times);
-			if (times !== void 0 && !(Number.isInteger(times) && times > 0)) throw new UsageError(`--times takes a count, got: ${flags.times}`);
+			if (times !== void 0 && !(Number.isInteger(times) && times > 0)) throw usage(`--times takes a count, and ${flags.times} isn't one.`);
 			const board = client();
 			const content = body === void 0 && flags.attach?.length ? "" : await text(body);
 			const files = await attachments(board);
@@ -1076,7 +1568,10 @@ async function run(command, args) {
 				...times !== void 0 ? { times } : {}
 			});
 			warnUnknownMentions(schedule.unknownMentions);
-			if (flags.json) printJson(schedule);
+			if (flags.json) result({
+				schedule,
+				outcome: "scheduled"
+			});
 			else out(formatSchedule(schedule));
 			return 0;
 		}
@@ -1087,102 +1582,135 @@ async function run(command, args) {
 				...flags.channel ? { channel: flags.channel } : {},
 				...flags.all ? { all: true } : {}
 			});
-			if (flags.json) return list.forEach(printJson), 0;
+			if (flags.json) return result({ schedules: list }), 0;
 			if (list.length === 0) return out(flags.all ? "no schedules" : "no pending schedules"), 0;
 			out(list.map((schedule) => formatSchedule(schedule)).join("\n"));
 			return 0;
 		}
 		case "hooks": {
 			const [action, ...names] = args;
-			if (action !== "uninstall") throw new UsageError(`\`${`${named()} hooks ${action ?? ""}`.trimEnd()}\` is gone: turn-end hooks were removed. Run \`${named()} hooks uninstall\` to clear an earlier install`);
+			if (action !== "uninstall") throw usage(`\`${`${named()} hooks ${action ?? ""}`.trimEnd()}\` is gone. Turn-end hooks were removed.`, {
+				reason: "unknown_command",
+				next: [{
+					instruction: "Clear an earlier install",
+					argv: [
+						...cli(),
+						"hooks",
+						"uninstall"
+					]
+				}]
+			});
 			const agents = hookAgents(names);
 			const width = Math.max(...agents.map((agent) => AGENTS[agent].name.length));
+			const hooks = [];
 			for (const agent of agents) {
 				const installed = installedHook(agent);
-				const cli = installed ? cliOf(installed) : null;
-				const rules = cli ? allowRules(agent, cli) : null;
+				const by = installed ? cliOf(installed) : null;
+				const rules = by ? allowRules(agent, by) : null;
 				if (rules) disallow(rules.file, rules.rules);
-				out([
+				const removed = uninstallHook(agent);
+				hooks.push({
+					agent,
+					outcome: removed ? "removed" : "unchanged",
+					file: installed ? AGENTS[agent].file() : null
+				});
+				if (!flags.json) out([
 					AGENTS[agent].name.padEnd(width),
-					uninstallHook(agent) ? "removed" : "not installed",
+					removed ? "removed" : "not installed",
 					installed ? tilde(AGENTS[agent].file()) : ""
 				].join("  ").trimEnd());
 			}
+			if (flags.json) result({ hooks });
 			return 0;
 		}
 		case "hook": return 0;
 		case "edit": {
-			const { unknownMentions } = await client().edit(messageId(args[0]), await text(args[1]));
+			const id = messageId(args[0]);
+			const { unknownMentions } = await client().edit(id, await text(args[1]));
 			warnUnknownMentions(unknownMentions);
+			printDone(id, "edited");
 			return 0;
 		}
-		case "delete":
-			await client().delete(messageId(args[0]));
+		case "delete": {
+			const id = messageId(args[0]);
+			await client().delete(id);
+			printDone(id, "deleted");
 			return 0;
+		}
 		case "react": {
 			const id = messageId(args[0]);
-			if (!args[1]) throw new UsageError(`usage: ${app.name} react <id> <emoji> [--remove]`);
+			if (!args[1]) throw usage("Missing the emoji to react with, like eyes or thumbs_up.", { reason: "missing_arguments" });
 			let emoji;
 			try {
 				emoji = normalizeEmoji(args[1]);
-			} catch (error) {
-				throw new UsageError(error.message);
+			} catch {
+				throw usage(`Unknown emoji ${args[1]}. Use a short name, like eyes or thumbs_up.`);
 			}
 			await client().react(id, emoji, flags.remove ? { remove: true } : {});
+			printDone(id, flags.remove ? "unreacted" : "reacted");
 			return 0;
 		}
 		case "label": {
 			const id = messageId(args[0]);
 			const set = labelPairs(args.slice(1));
 			const unset = flags.unset ?? [];
-			if (Object.keys(set).length === 0 && unset.length === 0) throw new UsageError(`usage: ${app.name} label <id> k=v... [--unset k]...`);
+			if (Object.keys(set).length === 0 && unset.length === 0) throw usage("Missing the labels: k=v to set one, --unset k to remove one.", { reason: "missing_arguments" });
 			await client().label(id, {
 				set,
 				unset
 			});
+			printDone(id, "labeled");
 			return 0;
 		}
 		case "typing": {
 			const id = messageId(args[0]);
 			const status = args.slice(1).join(" ").trim();
 			const targets = await client().typing(id, status || void 0);
-			if (flags.json) printJson({ targets });
+			if (flags.json) result({ targets });
 			return 0;
 		}
 		case "sync": {
 			const id = messageId(args[0]);
 			if (!args[1]) {
 				const { targets } = await client().sync(id);
-				if (flags.json) return targets.forEach(printJson), 0;
+				if (flags.json) return result({ targets }), 0;
 				out(targets.length ? formatSynced(targets) : "not synced anywhere");
 				return 0;
 			}
-			const result = await client().sync(id, args[1]);
-			if (flags.json) printJson(result);
-			else out(result.attached ? `synced with ${result.target}` : `already synced with ${result.target}`);
+			const synced = await client().sync(id, args[1]);
+			if (flags.json) result({
+				...synced,
+				outcome: synced.attached ? "synced" : "unchanged"
+			});
+			else out(synced.attached ? `synced with ${synced.target}` : `already synced with ${synced.target}`);
 			return 0;
 		}
 		case "download": {
 			const id = args[0];
-			if (!id) throw new UsageError(`usage: ${app.name} download <attachment> [path]   (the id \`${app.name} read\` shows on a file line)`);
+			if (!id) throw usage(`Missing the attachment to download: the ID \`${named()} read\` shows on a file line.`, { reason: "missing_arguments" });
 			const response = await client().download(id);
 			const data = new Uint8Array(await response.arrayBuffer());
 			if (args[1] === "-") return io.write(data), 0;
 			const disposition = response.headers.get("content-disposition") ?? "";
-			const named = /filename\*=UTF-8''([^;]+)/.exec(disposition)?.[1];
-			const path = args[1] ?? basename(named ? decodeURIComponent(named) : id);
+			const filename = /filename\*=UTF-8''([^;]+)/.exec(disposition)?.[1];
+			const path = args[1] ?? basename(filename ? decodeURIComponent(filename) : id);
 			await io.writeFile(path, data);
-			out(path);
+			if (flags.json) result({
+				attachment: { id },
+				path,
+				outcome: "downloaded"
+			});
+			else out(path);
 			return 0;
 		}
 		case "inbox": {
 			const key = args[0];
-			if (!key) throw new UsageError(`usage: ${app.name} inbox <key> [channel] [--limit N]`);
+			if (!key) throw usage("Missing the sync entry whose inbox to read, such as slack.", { reason: "missing_arguments" });
 			const events = await client().inbox(key, {
 				...args[1] ? { channel: args[1] } : {},
 				...flags.limit ? { limit: Number(flags.limit) } : {}
 			});
-			if (flags.json) return events.forEach(printJson), 0;
+			if (flags.json) return result({ events }), 0;
 			if (events.length === 0) return out("no events"), 0;
 			for (const entry of events) {
 				const event = entry.event;
@@ -1195,73 +1723,100 @@ async function run(command, args) {
 			const [key, sub, target] = args;
 			if (!key) {
 				const { sync } = await client().discovery();
-				if (flags.json) return sync.forEach(printJson), 0;
+				if (flags.json) return result({ sources: sync }), 0;
 				if (sync.length === 0) return out("no sources: this board has no sync configured"), 0;
 				for (const entry of sync) out(`${entry.key}  ${entry.platform}`);
 				return 0;
 			}
 			if (sub === "join" && target) {
 				const joined = await client().joinSource(key, target);
-				if (flags.json) return printJson(joined), 0;
+				if (flags.json) return result({
+					...joined,
+					outcome: joined.joined ? "joined" : "unchanged"
+				}), 0;
 				const label = joined.name ? `#${joined.name}` : joined.channel;
 				return out(joined.joined ? `joined ${label}` : `already in ${label}`), 0;
 			}
-			if (sub !== "read" || !target) throw new UsageError(`usage: ${app.name} sources <key> read <channel|thread|link> [--limit N], or sources <key> join <channel|link>`);
+			if (sub !== "read" && sub !== "join") throw usage(sub === void 0 ? `Missing what to do with ${key}: read or join.` : `Unknown command ${sub} for ${named()} sources.`, { reason: sub === void 0 ? "missing_arguments" : "unknown_command" });
+			if (!target) throw usage(`Missing the channel, thread, or link to ${sub}.`, { reason: "missing_arguments" });
 			const read = await client().readSource(key, target, flags.limit ? { limit: Number(flags.limit) } : {});
-			if (flags.json) return printJson(read), 0;
+			if (flags.json) return result(read), 0;
 			return out(formatSourceRead(key, read, Date.now(), named())), 0;
 		}
 		case "tail": {
 			const controller = new AbortController();
-			const release = stopOn(controller);
+			const stop = stopOn(controller);
 			try {
 				for await (const event of client().events({
 					...filters(args[0]),
 					...flags.all ? { all: true } : {}
-				}, { signal: controller.signal })) printEvent(event);
+				}, { signal: controller.signal })) if (flags.json) line(event);
+				else out(formatEvent(event));
 			} finally {
-				release();
+				stop.release();
 			}
-			return 0;
+			return stop.interrupted() ? 130 : 0;
 		}
 		case "wait": {
 			const controller = new AbortController();
-			const release = stopOn(controller);
+			const stop = stopOn(controller);
+			const timeout = flags.timeout ?? "30m";
 			const event = await client().wait(filters(args[0]), {
-				timeout: flags.timeout ?? "30m",
+				timeout,
 				signal: controller.signal
-			}).finally(release);
+			}).finally(stop.release);
 			if (!event) {
-				if (!controller.signal.aborted) io.error("timed out\n");
-				return 124;
+				if (controller.signal.aborted) return stop.interrupted() ? 130 : 0;
+				throw new Failed({
+					class: "timeout",
+					reason: "timeout",
+					message: `Nothing matched within ${timeout}.`
+				});
 			}
-			printEvent(event);
+			if (flags.json) result({ event });
+			else out(formatEvent(event));
 			return 0;
 		}
 		default: {
 			const own = app.commands[command];
 			if (own) return own.run(args, context());
-			throw new UsageError(`unknown command: ${command} (run \`${app.name} help\`)`);
+			const guess = closest(command, [...commands.flatMap((known) => [known.name, ...known.aliases ?? []]), ...Object.keys(app.commands)]);
+			throw usage(`Unknown command ${command} for ${named()}.${guess ? ` Did you mean ${guess}?` : ""}`, {
+				reason: "unknown_command",
+				next: [{
+					instruction: "See all commands",
+					argv: [...cli(), "--help"]
+				}]
+			});
 		}
 	}
 }
-/** Aborts `controller` on the run's signal, or Ctrl-C without one; the returned function stops listening. */
+/**
+* Aborts `controller` on the run's signal, or Ctrl-C without one. `release` stops listening, and
+* `interrupted` says whether Ctrl-C stopped it.
+*/
 function stopOn(controller) {
 	const stop = () => controller.abort();
 	if (io.signal) {
 		if (io.signal.aborted) stop();
 		io.signal.addEventListener("abort", stop, { once: true });
 		const signal = io.signal;
-		return () => signal.removeEventListener("abort", stop);
+		return {
+			release: () => signal.removeEventListener("abort", stop),
+			interrupted: () => false
+		};
 	}
 	process.once("SIGINT", stop);
-	return () => process.off("SIGINT", stop);
+	return {
+		release: () => process.off("SIGINT", stop),
+		interrupted: () => controller.signal.aborted
+	};
 }
 /** What a command an app adds gets: this run's flags, and the helpers board's own commands use. */
 const context = () => ({
 	flags,
 	out,
-	usage: (message) => new UsageError(message),
+	usage: (message) => usage(message),
 	portFlag,
 	connection,
 	client,
@@ -1269,31 +1824,46 @@ const context = () => ({
 });
 /**
 * Runs board's CLI on `argv` (what follows the command name) as `app`, and answers its exit
-* code: 0 success, 1 error, 2 misuse, 124 when `wait` times out. Errors are one `error: …` line
-* on stderr. A long-running command (`tail`, `serve`) answers once it's stopped.
+* code: 0 success, 1 error, 2 misuse, 124 when `wait` times out, 130 when Ctrl-C stops it. A
+* failure goes to `app.onError`, or to stderr: `error: ` and what failed, then how to fix it, or
+* with `--json`, one JSON document. A long-running command (`tail`, `serve`) answers once it's
+* stopped.
 */
 async function main(argv, options) {
 	app = options;
-	if (!parse(argv)) return 2;
-	if (flags.version) {
-		out(VERSION);
-		return 0;
-	}
-	if (flags.help) {
-		out(help(positionals));
-		return 0;
-	}
-	const [word, ...args] = positionals;
-	const command = canonical(word);
+	typed = argv;
+	flags = {};
+	positionals = [];
+	warnings = [];
+	reached = null;
 	try {
+		parse(argv);
+		if (flags.version) {
+			if (flags.json) result({ version: VERSION });
+			else out(VERSION);
+			return 0;
+		}
+		if (flags.help) {
+			out(help(positionals));
+			return 0;
+		}
+		const [word, ...args] = positionals;
+		const command = canonical(word);
+		current = {
+			command,
+			args
+		};
 		if (io.board) {
-			if (flags.url || flags.handle) throw new UsageError(`--${flags.url ? "url" : "handle"} doesn't apply: the board handle you pass says which board and who`);
-			if (command !== void 0 && MACHINE.has(command)) throw new UsageError(`${command} isn't available in-process: it's about the machine vb runs on`);
+			if (flags.url || flags.handle) throw usage(`--${flags.url ? "url" : "handle"} doesn't apply in-process: the board handle you pass says which board and who.`, { next: [] });
+			if (command !== void 0 && MACHINE.has(command)) throw usage(`${command} isn't available in-process: it's about the machine ${named()} runs on.`, {
+				reason: "not_available",
+				next: []
+			});
 		}
 		return await run(command, args);
 	} catch (error) {
-		io.error(`${terminalText(`error: ${error.message}`)}\n`);
-		return error instanceof UsageError ? 2 : 1;
+		const json = flags.json ?? argv.slice(0, argv.includes("--") ? argv.indexOf("--") : void 0).includes("--json");
+		return report(failureOf(error), json);
 	}
 }
 /** The commands about the machine the CLI runs on, not the board: none of them run in-process. */
@@ -1315,4 +1885,4 @@ async function mainWith(argv, options, with_) {
 	}
 }
 //#endregion
-export { who as i, main as n, mainWith as r, commandWord as t };
+export { commandLine as a, failureLines as c, mainWith as i, formatFailure as l, commandWord as n, exitCode as o, main as r, failureDocument as s, Failed as t, who as u };