@vercel/board 0.24.0 → 0.25.0

package/dist/{middleware-DUjyQP_a.mjs → middleware-B0J7QBq7.mjs}

@@ -1,5 +1,5 @@
 import { m as MESSAGE_TEXT_MAX, p as Labels } from "./schemas-Be08nyfW.mjs";
-import { t as HttpError } from "./errors-CQ-fwxM3.mjs";
+import { t as HttpError } from "./errors-Bven0k29.mjs";
 import { z } from "zod";
 //#region src/server/middleware.ts
 /** A write the middleware didn't let through: the API answers 422 with what it responded. */

package/dist/{node-CirFYqw0.mjs → node-C51_xzCb.mjs}

@@ -1,4 +1,4 @@
-import { t as BoardError } from "./client-ClznIBMg.mjs";
+import { t as BoardError } from "./client-BY-BCggB.mjs";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
@@ -99,7 +99,7 @@ function detectAgent(env = process.env) {
 		profile: named,
 		session: null
 	});
-	if (found.length > 1) throw new BoardError("ambiguous_agent", `several agent environments detected (${found.map((a) => a.profile).join(", ")}): choose one with a profile, or none`, 0);
+	if (found.length > 1) throw new BoardError("ambiguous_agent", `Several coding agents' environments are set (${found.map((a) => a.profile).join(", ")}), so it can't tell which one is writing.`, 0, { hint: "Pick one with a profile, or none to write as yourself." });
 	return found[0] ?? null;
 }
 const expiry = (token) => {
@@ -157,7 +157,7 @@ async function personToken(audience, discovery) {
 		return filled;
 	}
 	if (cached) return cached;
-	if (!discovery.project_id) throw new BoardError("no_project", `the board at ${discovery.url} doesn't know its Vercel project`, 0);
+	if (!discovery.project_id) throw new BoardError("no_project", `The board at ${discovery.url} doesn't know its Vercel project, so there's no Vercel login token to mint for it.`, 0, { hint: "Pass a token it accepts in BOARD_TOKEN." });
 	const authToken = await vercelLogin().catch(() => null);
 	const project = await boardProject(audience, discovery, authToken);
 	let development;
@@ -167,7 +167,7 @@ async function personToken(audience, discovery) {
 			method: "POST",
 			headers: { authorization: `Bearer ${authToken}` }
 		});
-		if (response.status === 403 || response.status === 404) throw new BoardError("no_access", "your Vercel account can't access this board's project: ask for access to it", response.status);
+		if (response.status === 403 || response.status === 404) throw new BoardError("no_access", "Your Vercel account can't access this board's project.", response.status, { hint: "Ask someone on the project's team for access to it." });
 		if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
 		development = (await response.json()).token;
 	} catch (error) {
@@ -210,8 +210,8 @@ async function boardProject(url, discovery, authToken) {
 		});
 		return response.ok ? await response.json() : null;
 	} : vercelCliApi, host);
-	if (!found) throw new BoardError("no_access", `your Vercel login can't see the project ${host} belongs to: run \`vercel login\` or ask for access to it`, 0);
-	if (found.projectId !== discovery.project_id) throw new BoardError("wrong_project", `the board at ${url} says its project is ${discovery.project_id}, but it's a deployment of ${found.projectId}, so vb won't sign in to it`, 0);
+	if (!found) throw new BoardError("no_access", `Your Vercel login can't see the project ${host} belongs to.`, 0, { hint: "Log in as someone on the project's team (vercel login), or ask for access to it." });
+	if (found.projectId !== discovery.project_id) throw new BoardError("wrong_project", `The board at ${url} says its project is ${discovery.project_id}, but it's a deployment of ${found.projectId}, so no token is minted for it.`, 0);
 	return {
 		id: found.projectId,
 		team: found.ownerId.startsWith("team_") ? found.ownerId : null
@@ -230,7 +230,7 @@ async function tokenFromVercelCli(project) {
 		const { stdout } = await promisify(execFile)("vercel", args, { timeout: 3e4 });
 		return JSON.parse(stdout).token;
 	} catch {
-		throw new BoardError("not_logged_in", "not signed in to Vercel: run `vercel login`", 0);
+		throw new BoardError("not_logged_in", "You're not logged in to Vercel.", 0, { hint: "Run vercel login." });
 	}
 }
 /** Your Vercel username, display name, and avatar (Vercel serves avatars publicly). */
@@ -252,13 +252,13 @@ async function githubActionsToken(audience) {
 	const url = new URL(process.env.ACTIONS_ID_TOKEN_REQUEST_URL);
 	url.searchParams.set("audience", audience);
 	const response = await fetch(url, { headers: { authorization: `bearer ${process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN}` } });
-	if (!response.ok) throw new BoardError("no_token", `GitHub Actions refused an OIDC token (${response.status}): does the job have \`permissions: id-token: write\`?`, 0);
+	if (!response.ok) throw new BoardError("no_token", `GitHub Actions refused an OIDC token (${response.status}).`, 0, { hint: "Give the job `permissions: id-token: write`." });
 	return (await response.json()).value;
 }
 /** The board the environment points at: `BOARD_URL`. */
 function boardUrl() {
 	const url = process.env.BOARD_URL?.replace(/\/+$/, "");
-	if (!url) throw new BoardError("no_board", "no board URL: set BOARD_URL", 0);
+	if (!url) throw new BoardError("no_board", "There's no board URL: BOARD_URL isn't set.", 0, { hint: "Set BOARD_URL, or pass the URL to http()." });
 	return url;
 }
 /**
@@ -272,9 +272,9 @@ function connect(url, options = {}) {
 	const doFetch = guarded(url, options.fetch ?? ((input, init) => globalThis.fetch(input, init)), options.token);
 	let discovery;
 	const discover = () => discovery ??= doFetch(url).then(async (response) => {
-		if (!response.ok) throw new BoardError("no_board", `no board at ${url} (${response.status})`, response.status);
+		if (!response.ok) throw new BoardError("no_board", `There's no board at ${url}: it answered ${response.status}.`, response.status);
 		const found = await response.json();
-		if (found.audience !== url) throw new BoardError("wrong_audience", `the board at ${url} says its URL is ${found.audience}: use that URL`, 0);
+		if (found.audience !== url) throw new BoardError("wrong_audience", `The board at ${url} says its URL is ${found.audience}.`, 0, { hint: `Use ${found.audience}.` });
 		return found;
 	});
 	let cached = null;
@@ -388,7 +388,7 @@ async function hostedToken(url) {
 	try {
 		return await getVercelOidcToken({ audience: url });
 	} catch (cause) {
-		throw Object.assign(new BoardError("no_token", `cannot obtain Vercel OIDC credentials for ${url}: enable OIDC on the calling project or supply token / BOARD_TOKEN; configure Deployment Protection Trusted Sources for its project and environment`, 0), { cause });
+		throw Object.assign(new BoardError("no_token", `This deployment can't get a Vercel OIDC token for ${url}.`, 0, { hint: "Enable OIDC on its project, or pass a token (BOARD_TOKEN), and add its project to the board project's Deployment Protection Trusted Sources." }), { cause });
 	}
 }
 /** A host this deployment answers on, as Vercel's system variables name them (bare hosts). */
@@ -414,7 +414,7 @@ function guarded(url, doFetch, suppliedToken) {
 			return await through(doFetch, input, init, fromEnv);
 		} catch (error) {
 			if (!(error instanceof Wall)) throw error;
-			if (process.env.VERCEL !== "1") throw new BoardError("protected", `${url} is behind Vercel Deployment Protection and rejected VERCEL_AUTOMATION_BYPASS_SECRET; check it against ${WHERE}`, error.status);
+			if (process.env.VERCEL !== "1") throw new BoardError("protected", `${url} is behind Vercel Deployment Protection, and it rejected VERCEL_AUTOMATION_BYPASS_SECRET.`, error.status, { hint: `Check VERCEL_AUTOMATION_BYPASS_SECRET against ${WHERE}.` });
 			envRejected = true;
 		}
 		if (process.env.VERCEL === "1") {
@@ -423,7 +423,7 @@ function guarded(url, doFetch, suppliedToken) {
 				headers.set("x-vercel-trusted-oidc-idp-token", token);
 			}
 			return through(doFetch, input, init, null).catch((error) => {
-				throw error instanceof Wall ? new BoardError("protected", `${url} rejected Vercel OIDC access: configure Deployment Protection Trusted Sources for the calling project and environment`, error.status) : error;
+				throw error instanceof Wall ? new BoardError("protected", `${url} is behind Vercel Deployment Protection, and it rejected this deployment's Vercel OIDC token.`, error.status, { hint: "Add this project and environment to the board project's Deployment Protection Trusted Sources." }) : error;
 			});
 		}
 		const used = await (secret ??= readBypass(host));
@@ -445,7 +445,7 @@ function guarded(url, doFetch, suppliedToken) {
 				return through(doFetch, input, init, found);
 			});
 		} catch (error) {
-			throw error instanceof Wall ? new BoardError("protected", `${url} is behind Vercel Deployment Protection and its project's automation bypass didn't get through; set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE})`, error.status) : error;
+			throw error instanceof Wall ? new BoardError("protected", `${url} is behind Vercel Deployment Protection, and its project's automation bypass didn't get through.`, error.status, { hint: `Set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE}).` }) : error;
 		}
 	};
 }
@@ -475,7 +475,7 @@ async function through(doFetch, input, init, bypass) {
 			const next = new URL(location, target);
 			if (next.pathname.startsWith("/sso-api")) throw new Wall(response.status);
 			if (method === "GET" || method === "HEAD") {
-				if (hops >= 20) throw new BoardError("too_many_redirects", `too many redirects from ${target}`, response.status);
+				if (hops >= 20) throw new BoardError("too_many_redirects", `${target} redirected more than 20 times.`, response.status);
 				if (next.origin !== new URL(target).origin) {
 					headers = new Headers(headers);
 					headers.delete("authorization");
@@ -517,7 +517,7 @@ const automationBypass = (bypasses) => Object.entries(bypasses ?? {}).find(([, v
 * `protectionBypass` has it. When there's none, it's created.
 */
 async function projectBypass(url, host, doFetch) {
-	const blocked = (why) => new BoardError("protected", `${url} is behind Vercel Deployment Protection, and your Vercel login ${why}, or set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE})`, 0);
+	const blocked = (why, fix) => new BoardError("protected", `${url} is behind Vercel Deployment Protection, and your Vercel login ${why}.`, 0, { hint: `${fix}, or set VERCEL_AUTOMATION_BYPASS_SECRET (${WHERE}).` });
 	let api;
 	try {
 		const token = await vercelLogin();
@@ -536,19 +536,19 @@ async function projectBypass(url, host, doFetch) {
 		api = vercelCliApi;
 	}
 	const project = await findProject(api, host);
-	if (!project) throw blocked("can't see its project: run `vercel login` or ask for access");
+	if (!project) throw blocked("can't see its project", "Log in as someone on its project's team (vercel login), ask for access");
 	const scope = project.ownerId.startsWith("team_") ? `?teamId=${project.ownerId}` : "";
 	const details = await api("GET", `/v9/projects/${project.projectId}${scope}`);
-	if (!details) throw blocked("can't read its project's settings: ask for access");
+	if (!details) throw blocked("can't read its project's settings", "Ask for access to its project");
 	const existing = automationBypass(details.protectionBypass);
 	if (existing) return {
 		secret: existing,
 		created: false
 	};
-	if (!details.ssoProtection && !details.passwordProtection && !details.passport) throw new BoardError("no_board", `no board at ${url}: it answered with a web page, and its Vercel project isn't protected`, 0);
+	if (!details.ssoProtection && !details.passwordProtection && !details.passport) throw new BoardError("no_board", `There's no board at ${url}: it answered with a web page, and its Vercel project isn't protected.`, 0);
 	const created = await api("PATCH", `/v1/projects/${project.projectId}/protection-bypass${scope}`);
 	const secret = automationBypass(created?.protectionBypass);
-	if (!secret) throw blocked("can't read or create its project's automation bypass: ask a project admin");
+	if (!secret) throw blocked("can't read or create its project's automation bypass", "Ask a project admin to create one");
 	process.stderr.write(`created a Protection Bypass for Automation on the Vercel project ${details?.name ?? project.projectId}\n`);
 	return {
 		secret,
@@ -579,7 +579,7 @@ async function findProject(api, host) {
 let vercelCli;
 const vercelCliApi = async (method, path) => {
 	vercelCli ??= promisify(execFile)("vercel", ["whoami", "--non-interactive"], { timeout: 1e4 }).then(() => true, () => false);
-	if (!await vercelCli) throw new BoardError("not_logged_in", "not signed in to Vercel: run `vercel login`", 0);
+	if (!await vercelCli) throw new BoardError("not_logged_in", "You're not logged in to Vercel.", 0, { hint: "Run vercel login." });
 	const args = [
 		"api",
 		path,
@@ -595,7 +595,7 @@ const vercelCliApi = async (method, path) => {
 		run.child.stdin?.end(method === "PATCH" ? "{}" : "");
 		return JSON.parse((await run).stdout);
 	} catch (error) {
-		if (error.code === "ENOENT") throw new BoardError("not_logged_in", "not signed in to Vercel: run `vercel login`", 0);
+		if (error.code === "ENOENT") throw new BoardError("not_logged_in", "You're not logged in to Vercel.", 0, { hint: "Run vercel login." });
 		return null;
 	}
 };

package/dist/{provider-D11Dfda0.d.mts → provider-C_sj4-GL.d.mts}

@@ -919,10 +919,12 @@ type SourceJoin = {
   name: string | null;
   joined: boolean;
 };
+/** A failure: `code` to branch on, `message` to read, and `hint`, when the board knows one, for what fixes it. */
 type ApiError = {
   error: {
     code: string;
     message: string;
+    hint?: string;
   };
 };
 /** A raw platform event, as `GET /inbox/:key` returns it. */
@@ -1696,10 +1698,17 @@ declare const routes: {
 type RouteName = keyof typeof routes;
 //#endregion
 //#region src/client/client.d.ts
+/**
+ * What went wrong: `message` says what and why, `code` is what to branch on, and `hint`, when the
+ * handle knows one, says what fixes it (`Set VERCEL_AUTOMATION_BYPASS_SECRET…`).
+ */
 declare class BoardError extends Error {
   readonly code: string;
   readonly status: number;
-  constructor(code: string, message: string, status: number);
+  readonly hint: string | undefined;
+  constructor(code: string, message: string, status: number, options?: {
+    hint?: string;
+  });
 }
 type Resolvable<T> = T | (() => T | Promise<T>);
 /** A profile name, `{ name, avatar }`, or null for no profile. */

package/dist/{serve-DHyA-6FR.mjs → serve-DYQ64Q5R.mjs}

@@ -1,7 +1,8 @@
-import { i as localTokenFile } from "./node-CirFYqw0.mjs";
-import { t as board } from "./server-Cp2oIQOj.mjs";
-import { t as oidcTokens } from "./tokens-DUXaXwOj.mjs";
-import { n as fsBlob, t as a2 } from "./a2-BxfKZFvJ.mjs";
+import { t as BoardError } from "./client-BY-BCggB.mjs";
+import { i as localTokenFile } from "./node-C51_xzCb.mjs";
+import { t as board } from "./server-BgK1sgj7.mjs";
+import { t as oidcTokens } from "./tokens-U-XRlEfq.mjs";
+import { n as fsBlob, t as a2 } from "./a2-CQ3WcqMv.mjs";
 import { t as localScheduler } from "./local-DhkrAqPP.mjs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { userInfo } from "node:os";
@@ -53,7 +54,7 @@ async function serveLocal(options) {
 		port = await listen(server, options.port ?? 4100);
 	} catch (error) {
 		await store.close();
-		if (error.code === "EADDRINUSE") throw new Error(`port ${options.port ?? 4100} is taken: is a board already running? Pick another with --port`);
+		if (error.code === "EADDRINUSE") throw new BoardError("port_taken", `Port ${options.port ?? 4100} is taken. Is a board already running there?`, 0);
 		throw error;
 	}
 	const url = `http://127.0.0.1:${port}/api/board`;

package/dist/{server-Cp2oIQOj.mjs → server-BgK1sgj7.mjs}

@@ -1,5 +1,5 @@
-import { t as createBoard } from "./exports-Bw81oDDl.mjs";
-import { t as http } from "./backend-http-tGUo0e8j.mjs";
+import { t as createBoard } from "./exports-ByvYtxFT.mjs";
+import { t as http } from "./backend-http-Cs-UKpYp.mjs";
 //#region src/server/index.ts
 /**
 * The handle on a board. With a `backend`, the board lives there: `a2()` keeps it in this
@@ -9,8 +9,8 @@ import { t as http } from "./backend-http-tGUo0e8j.mjs";
 function board(options = {}) {
 	return createBoard(options, {
 		http: () => http(),
-		sync: () => import("./engine-kHfSOXnQ.mjs"),
-		serving: () => import("./serving-B307gppu.mjs")
+		sync: () => import("./engine-SeaJ_CIY.mjs"),
+		serving: () => import("./serving-rXQcEgTO.mjs")
 	});
 }
 //#endregion

package/dist/{serving-B307gppu.mjs → serving-rXQcEgTO.mjs}

@@ -1,2 +1,2 @@
-import { i as ownTeamId, n as discoveryIdentity, r as ownProjectId, t as oidcTokens } from "./tokens-DUXaXwOj.mjs";
+import { i as ownTeamId, n as discoveryIdentity, r as ownProjectId, t as oidcTokens } from "./tokens-U-XRlEfq.mjs";
 export { discoveryIdentity, oidcTokens, ownProjectId, ownTeamId };

package/dist/sync-github.d.mts

@@ -1,5 +1,5 @@
-import { S as SyncUnit, _ as withUserTokens, d as ResolvedTarget, f as SyncContext, h as UserTokens, o as ProviderPost, r as ProviderDelivery, y as SyncFn } from "./provider-D11Dfda0.mjs";
-import { n as ChatSyncProvider } from "./chat-provider-D0k3y8zY.mjs";
+import { S as SyncUnit, _ as withUserTokens, d as ResolvedTarget, f as SyncContext, h as UserTokens, o as ProviderPost, r as ProviderDelivery, y as SyncFn } from "./provider-C_sj4-GL.mjs";
+import { n as ChatSyncProvider } from "./chat-provider-6eYkL2ef.mjs";
 import { z } from "zod";
 import { Adapter } from "chat";
 //#region src/sync/github.d.ts

package/dist/sync-kapso.d.mts

@@ -1,5 +1,5 @@
-import { S as SyncUnit, f as SyncContext, y as SyncFn } from "./provider-D11Dfda0.mjs";
-import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-D0k3y8zY.mjs";
+import { S as SyncUnit, f as SyncContext, y as SyncFn } from "./provider-C_sj4-GL.mjs";
+import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-6eYkL2ef.mjs";
 import { z } from "zod";
 import { Adapter } from "chat";
 //#region src/sync/kapso.d.ts

package/dist/sync-linear.d.mts

@@ -1,5 +1,5 @@
-import { S as SyncUnit, c as ReceivedEvent, d as ResolvedTarget, f as SyncContext, o as ProviderPost, r as ProviderDelivery, y as SyncFn } from "./provider-D11Dfda0.mjs";
-import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-D0k3y8zY.mjs";
+import { S as SyncUnit, c as ReceivedEvent, d as ResolvedTarget, f as SyncContext, o as ProviderPost, r as ProviderDelivery, y as SyncFn } from "./provider-C_sj4-GL.mjs";
+import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-6eYkL2ef.mjs";
 import { z } from "zod";
 import { Adapter } from "chat";
 //#region src/sync/linear.d.ts

package/dist/sync-slack.d.mts

@@ -1,6 +1,6 @@
 import { f as ExternalLink } from "./folds-CRYY14kc.mjs";
-import { C as channels, _ as withUserTokens, d as ResolvedTarget, f as SyncContext, h as UserTokens, o as ProviderPost, r as ProviderDelivery, y as SyncFn } from "./provider-D11Dfda0.mjs";
-import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-D0k3y8zY.mjs";
+import { C as channels, _ as withUserTokens, d as ResolvedTarget, f as SyncContext, h as UserTokens, o as ProviderPost, r as ProviderDelivery, y as SyncFn } from "./provider-C_sj4-GL.mjs";
+import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-6eYkL2ef.mjs";
 import { z } from "zod";
 import { Adapter } from "chat";
 //#region src/sync/slack.d.ts

package/dist/sync.chat.d.mts

@@ -1,2 +1,2 @@
-import { i as externalAuthor, n as ChatSyncProvider, r as ChatTransport, t as ChatInput } from "./chat-provider-D0k3y8zY.mjs";
+import { i as externalAuthor, n as ChatSyncProvider, r as ChatTransport, t as ChatInput } from "./chat-provider-6eYkL2ef.mjs";
 export { ChatInput, ChatSyncProvider, ChatTransport, externalAuthor };

package/dist/sync.d.mts

@@ -1,3 +1,3 @@
 import { d as ExternalFile, l as ExternalAuthor, u as ExternalEvent } from "./folds-CRYY14kc.mjs";
-import { A as SyncOverrides, C as channels, D as EventBase, E as render, M as SyncRoot, N as envelope, O as ProviderEvent, P as eventSchema, S as SyncUnit, T as mirror, _ as withUserTokens, a as ProviderOptions, b as SyncIn, c as ReceivedEvent, d as ResolvedTarget, f as SyncContext, g as connectUserTokens, h as UserTokens, i as ProviderFile, j as SyncResult, k as RootOverride, l as RenderInput, m as UnreadableError, n as FileDelivery, o as ProviderPost, p as SyncProvider, r as ProviderDelivery, s as Receive, u as Renderer, v as Sync, w as into, x as SyncOut, y as SyncFn } from "./provider-D11Dfda0.mjs";
+import { A as SyncOverrides, C as channels, D as EventBase, E as render, M as SyncRoot, N as envelope, O as ProviderEvent, P as eventSchema, S as SyncUnit, T as mirror, _ as withUserTokens, a as ProviderOptions, b as SyncIn, c as ReceivedEvent, d as ResolvedTarget, f as SyncContext, g as connectUserTokens, h as UserTokens, i as ProviderFile, j as SyncResult, k as RootOverride, l as RenderInput, m as UnreadableError, n as FileDelivery, o as ProviderPost, p as SyncProvider, r as ProviderDelivery, s as Receive, u as Renderer, v as Sync, w as into, x as SyncOut, y as SyncFn } from "./provider-C_sj4-GL.mjs";
 export { EventBase, type ExternalAuthor, ExternalEvent, type ExternalFile, type FileDelivery, type ProviderDelivery, type ProviderEvent, type ProviderFile, type ProviderOptions, type ProviderPost, type Receive, ReceivedEvent, type RenderInput, type Renderer, ResolvedTarget, type RootOverride, type Sync, type SyncContext, type SyncFn, type SyncIn, type SyncOut, SyncOverrides, SyncProvider, type SyncResult, type SyncRoot, type SyncUnit, UnreadableError, type UserTokens, channels, connectUserTokens, envelope, eventSchema, into, mirror, render, withUserTokens };

package/dist/{tokens-DUXaXwOj.mjs → tokens-U-XRlEfq.mjs}

@@ -1,5 +1,5 @@
-import { l as unauthorized } from "./errors-CQ-fwxM3.mjs";
-import { f as markVerified, m as trustedIssuers, n as TOKENS, r as VERCEL_ISSUER, u as issuerName } from "./auth-5nLsx9qB.mjs";
+import { l as unauthorized } from "./errors-Bven0k29.mjs";
+import { f as markVerified, m as trustedIssuers, n as TOKENS, r as VERCEL_ISSUER, u as issuerName } from "./auth-BwWH3Twu.mjs";
 import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
 //#region src/server/identity.ts
 let fromDisk;

package/dist/{watchers-hash-C_1jGA53.mjs → watchers-hash-C4CJg7K1.mjs}

@@ -1,7 +1,7 @@
 import { n as DIRECT_UPLOAD_BYTES_MAX, t as ATTACHMENT_BYTES_MAX } from "./files-SniSmeEr.mjs";
 import { S as storable, a as AttachmentId, c as ChannelPath, d as LabelKey, g as MessageText, l as Emoji, m as MESSAGE_TEXT_MAX, n as ActorId, p as Labels, x as platformAvatar } from "./schemas-Be08nyfW.mjs";
 import { a as Link, i as ExternalTarget, n as ExternalEvent, o as Origin, t as ExternalAuthor } from "./external-BV_cUncs.mjs";
-import { r as badRequest, t as HttpError } from "./errors-CQ-fwxM3.mjs";
+import { r as badRequest, t as HttpError } from "./errors-Bven0k29.mjs";
 import { o as options } from "./commands-BtL4jFq8.mjs";
 import { z } from "zod";
 //#region src/api/routes.ts
@@ -662,7 +662,7 @@ const routes = {
 const SYNC = "@sync";
 //#endregion
 //#region src/version.ts
-const VERSION = "0.24.0";
+const VERSION = "0.25.0";
 //#endregion
 //#region src/server/routing.ts
 /** board()'s own routes: the files it serves, and sync's, which run where board() does. */

package/docs/01-board/03-identity.md

@@ -67,18 +67,26 @@ source  vercel login
 token   expires in 11h 42m
 ```
 
-When it can't, it says what fixes it:
+When it can't, it says why, then what fixes it:
 
 ```text
-error: not signed in to Vercel: run `vercel login`
-error: your Vercel login can't see the project www.example.com belongs to: run `vercel login` or ask for access to it
-error: your Vercel account can't access this board's project: ask for access to it
+$ vb whoami
+error: You're not logged in to Vercel.
+
+  Log in:
+    vercel login
+```
+
+```text
+error: Your Vercel login can't see the project www.example.com belongs to.
+
+  Log in as someone on the project's team (vercel login), or ask for access to it.
 ```
 
 When the board's host is another project's deployment, it gets no token:
 
 ```text
-error: the board at https://www.example.com/api/board says its project is prj_abc123, but it's a deployment of prj_def456, so vb won't sign in to it
+error: The board at https://www.example.com/api/board says its project is prj_abc123, but it's a deployment of prj_def456, so no token is minted for it.
 ```
 
 ## How the board verifies
@@ -248,10 +256,11 @@ vb reply 812 "@ada can you look? cc @julian/claude"
 
 ```text
 $ vb post errors-www "@ada the rollback is live"
-error: ambiguous mention @ada: use @[slack:user:U0456] (ada) or @[vercel:user:u_9f] (ada)
+error: Can't post to errors-www.
+  ambiguous mention @ada: use @[slack:user:U0456] (ada) or @[vercel:user:u_9f] (ada)
 ```
 
-An `@[actor-id]` the board doesn't know fails with `error: unknown actor`. For
+An `@[actor-id]` the board doesn't know fails too, the board saying `unknown actor`. For
 a caller that can't read every channel, an ambiguous mention lists no
 candidates: `use @[actor-id]`. A caller that can't read the channel it writes
 in gets no warning for a handle no one has, since it would say which handles

package/docs/01-board/04-messages.md

@@ -142,8 +142,8 @@ vb download nXHY2NjUHuzE5F1QpXyBdQ            # saves after.png here; a path, or
   board's copy. See [Sync](../02-sync/01-overview.md).
 - **They need a blob store.** A board on `a2()` without one keeps no files:
   an upload, a post or schedule that carries files, and a download answer 501
-  `no_files`, and `vb` prints
-  ``error: this board keeps no files: pass `blob` to `a2()` ``. Sync brings a
+  `no_files`, and `vb` says it can't, with the board's words under it:
+  ``this board keeps no files: pass `blob` to `a2()` ``. Sync brings a
   platform's files over as links to where they live instead. See
   [Mounting](./01-mounting.md#without-a-blob-store).
 

package/docs/01-board/05-reading.md

@@ -28,12 +28,19 @@ errors-www · 2 threads · cursor 815
   pending [scheduled messages](./07-schedules.md).
 - **`vb read`** with no channel reads across every channel, and each summary
   names its channel.
-- **`--json`** prints one `{ message, replies, last }` per line (JSONL): the
-  root, its reply count, and its latest reply or `null`. `vb read <id> --json`
-  prints one message per line.
+- **`--json`** prints `{ threads, cursor }`, each thread `{ message, replies,
+  last }`: the root, its reply count, and its latest reply or `null`.
 
-A channel that doesn't exist is an error (`no channel errors-wwww`), so a typo
-doesn't read as an empty channel.
+A channel that doesn't exist is an error, so a typo doesn't read as an empty
+channel:
+
+```text
+$ vb read errors-wwww
+error: Couldn't find channel errors-wwww. Did you mean errors-www?
+
+  See its channels:
+    vb channels
+```
 
 ## One thread
 
@@ -49,7 +56,7 @@ $ vb read 812
 ```
 
 `vb read <id>` prints every message in the thread, oldest first, and `--json`
-prints one message per line. Filters narrow it to the root and the replies that
+prints `{ message, replies, cursor, schedules }`. Filters narrow it to the root and the replies that
 match: `vb read 812 --by ada --label status=investigating`. Each reaction
 names its first three people and counts the rest (`👀 ada, claude, codex +9`);
 `--json` has them all.
@@ -125,8 +132,9 @@ vb wait --re 812 --timeout 30m
 ```
 
 `vb wait [channel] [filters]` blocks until the next matching event, prints it,
-and exits 0. If nothing matches in time it prints `timed out` on stderr and
-exits 124, the GNU `timeout` convention. The timeout defaults to `30m` and takes
+and exits 0. If nothing matches in time it says so on stderr
+(`error: Nothing matched within 30m.`) and exits 124, the GNU `timeout`
+convention. The timeout defaults to `30m` and takes
 `30s`, `10m`, `1h`, or `1d`.
 
 Like `tail`, it starts at the head. Pass `--after` to start from a known

package/docs/01-board/07-schedules.md

@@ -105,8 +105,8 @@ await team.cancelSchedule(reminder.id)   // { schedule, canceled }
 
 - **It runs on the scheduler.** A board on `a2()` without one refuses:
   `POST /schedules`, `schedule()`, and `vb schedule` answer 501
-  `no_scheduler`, and `vb` prints
-  ``error: this board has no scheduler: pass `scheduler` to `a2()` to send later``.
+  `no_scheduler`, and `vb` says it can't, with the board's words under it:
+  ``this board has no scheduler: pass `scheduler` to `a2()` to send later``.
   See [Without a scheduler](./01-mounting.md#without-a-scheduler). In
   production, pass `vercelQueues()` or `qstash()` and mount
   [its route](./01-mounting.md#the-scheduler-route). On a dev server, in

package/docs/01-board/09-access.md

@@ -25,14 +25,15 @@ The board's environment is the one Vercel runs it in (`VERCEL_TARGET_ENV`,
 which names custom environments, or `VERCEL_ENV`). A production board trusts
 its production and refuses its previews, which run any branch's code. A
 preview board trusts its own previews, so a preview can call itself. Outside
-Vercel, only people get in without a rule.
+Vercel, only people get in without a rule. A refused token gets a 403 that
+says what would let it in:
 
 ```text
-error: this token can't use this board: it runs in production, so its preview deployments need vercelProject({ project: 'self', environments: ['preview'], can })
+this token can't use this board: it runs in production, so its preview deployments need vercelProject({ project: 'self', environments: ['preview'], can })
 ```
 
 A token no rule matches is refused the same way, with the rule that would let
-it in: `error: this token can't use this board: add githubActions({ repository:
+it in: `this token can't use this board: add githubActions({ repository:
 'acme/www', can }) to access`.
 
 ## Configure it
@@ -408,7 +409,7 @@ Reads show only what the caller can read, everywhere:
 - **What you can't read answers 404,** as if it didn't exist. On `a2()`,
   message IDs are sequential, so a 403 would confirm a message is there.
 - **A refused write you can read answers 403** and names what's missing:
-  `error: this token can't label in dev`.
+  `this token can't label in dev`.
 - **A channel the request names is yours to know,** so a post to a channel you
   can't post in is 403, read or not.
 - **Every check is against the channel the board looked up.** A reply's

package/docs/03-guides/01-coding-agents.md

@@ -21,7 +21,7 @@ which team.
 - **Credentials stay with you.** You sign in with your own `vercel login`,
   and tokens are cached per user. Access to the board is access to its Vercel
   project: an account without it gets
-  `error: your Vercel account can't access this board's project: ask for access to it`.
+  `error: Your Vercel account can't access this board's project.`
 - **The URL picks a board, not a channel.** Agents choose channels per task.
 
 Every command finds the board in this order, and the first match wins:
@@ -61,7 +61,9 @@ saying so), keep it per host in `~/.config/board/bypass/`, and send it as
 sent instead. When neither gets through, the CLI says why:
 
 ```text
-error: https://team.example/api/board is behind Vercel Deployment Protection, and your Vercel login can't see its project: run `vercel login` or ask for access, or set VERCEL_AUTOMATION_BYPASS_SECRET (Project → Settings → Deployment Protection → Protection Bypass for Automation)
+error: https://team.example/api/board is behind Vercel Deployment Protection, and your Vercel login can't see its project.
+
+  Log in as someone on its project's team (vercel login), ask for access, or set VERCEL_AUTOMATION_BYPASS_SECRET (Project → Settings → Deployment Protection → Protection Bypass for Automation).
 ```
 
 ## Install the skill

package/docs/03-guides/03-ci.md

@@ -72,8 +72,8 @@ export const GET = team.fetch, POST = team.fetch
 `githubActions()` matches the token's `repository`, plus `workflow`, `event`
 (`push`, `pull_request`, or a list), and `ref` when you give them. The
 workflow posts as `github:repo:<repository_id>`, with the handle
-`acme/www`. A workflow that matches no rule gets
-`error: this token can't use this board: add githubActions({ repository: 'acme/www', can }) to access`.
+`acme/www`. A workflow that matches no rule gets a 403:
+`this token can't use this board: add githubActions({ repository: 'acme/www', can }) to access`.
 
 `can` says what it may do where. This one posts and labels in `errors-www`, for
 the step above, and reads and posts in `deploys`, which the wait below needs.