@vercel/board 0.24.0 → 0.25.1

package/dist/{serve-DHyA-6FR.mjs → serve-D2O0C6Kk.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-D0Px7KzF.mjs";
+import { i as localTokenFile } from "./node-Bkd1x0QI.mjs";
+import { t as board } from "./server-BF4WJ7qi.mjs";
+import { t as oidcTokens } from "./tokens-BuCU-61R.mjs";
+import { n as fsBlob, t as a2 } from "./a2-A830f5NS.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-BF4WJ7qi.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-DCqgO_mr.mjs";
+import { t as http } from "./backend-http-CJd4Fu0U.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-ROa7-IQY.mjs"),
+		serving: () => import("./serving-CvOWEym2.mjs")
 	});
 }
 //#endregion

package/dist/{serving-B307gppu.mjs → serving-CvOWEym2.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-BuCU-61R.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-Cdg1qadh.mjs";
+import { n as ChatSyncProvider } from "./chat-provider-DsNEBQiA.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-Cdg1qadh.mjs";
+import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-DsNEBQiA.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-Cdg1qadh.mjs";
+import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-DsNEBQiA.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 { f as ExternalLink } from "./folds-jS9wlh9_.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-Cdg1qadh.mjs";
+import { n as ChatSyncProvider, t as ChatInput } from "./chat-provider-DsNEBQiA.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-DsNEBQiA.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 { d as ExternalFile, l as ExternalAuthor, u as ExternalEvent } from "./folds-jS9wlh9_.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-Cdg1qadh.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-BuCU-61R.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-CusN4x2l.mjs";
+import { f as markVerified, m as trustedIssuers, n as TOKENS, r as VERCEL_ISSUER, u as issuerName } from "./auth-lTkOgvcE.mjs";
 import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
 //#region src/server/identity.ts
 let fromDisk;

package/dist/{types-8yq2VnKI.d.mts → types-aCAf6lGU.d.mts}

@@ -1,4 +1,4 @@
-import { a as ExternalCopy, c as SyncedThread, g as BoardEvent, o as Message } from "./folds-CRYY14kc.mjs";
+import { a as ExternalCopy, c as SyncedThread, g as BoardEvent, o as Message } from "./folds-jS9wlh9_.mjs";
 import { t as A2Store } from "./store-D0MhBvg6-4Z2L0Kqd.mjs";
 //#region src/store/types.d.ts
 /**

package/dist/{watchers-hash-C_1jGA53.mjs → watchers-hash-BHNXy_N7.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-CusN4x2l.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.1";
 //#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.

package/docs/04-reference/01-cli.md

@@ -35,7 +35,25 @@ import { createApp } from '@vercel/board/cli'
 const code = await createApp({ appName: 'vercel board' }).run(process.argv.slice(3))
 ```
 
-`run` answers the exit code, and never exits the process itself.
+`run` answers the exit code, and never exits the process itself. A failure is
+data too, for the CLI that runs board to show as it shows its own:
+
+```ts
+import { createApp, failureLines } from '@vercel/board/cli'
+
+const code = await createApp({
+  appName: 'vercel board',
+  // { class, reason, message, details, next: [{ instruction, argv }], data, … }
+  onError: (failure, { json }) => console.error(json ? JSON.stringify(failure) : failureLines(failure).join('\n')),
+  // { reason, message }: a write that went through, with something to say. With --json, it's in the result.
+  onWarning: (warning) => console.error(warning.message),
+}).run(process.argv.slice(3))
+```
+
+`class` fixes the exit code: `usage` and `missing_input` answer 2,
+`timeout` 124, `canceled` 130, and the rest 1. Without `onError`, board
+prints its own on stderr: `error: ` and the lines, or with `--json`, its
+[JSON document](#errors).
 
 The commands are data too, in `@vercel/board/cli/commands`, which imports
 nothing: each command's name, description, arguments, options, examples, and
@@ -141,10 +159,11 @@ hyphens. Avatars are `https` URLs (`http` only on localhost).
 - **What's written can't drive your terminal.** A message's control
   characters, ESC among them, print as their pictures (`␛`), and `--json`
   prints them as the board has them.
-- **On a terminal, output is for people.** `--json` prints JSONL instead: one
-  object per line, each a message, event, channel, actor, or schedule as the
-  [HTTP API](./03-http.md#routes) sends it. See [JSON output](#json-output).
-- **Writes print the new message's ID** on stdout (the whole message with
+- **On a terminal, output is for people.** `--json` prints one JSON document
+  instead, with what's in it as the [HTTP API](./03-http.md#routes) sends it,
+  indented at a terminal. `tail` prints one object per line, as they come. See
+  [JSON output](#json-output).
+- **Writes print the new message's ID** on stdout (`{ message, outcome }` with
   `--json`), so a script can chain them: `id=$(vb post ops "…")`. A number
   prints as it is (`812`); any other ID prints with its `#` (`#msg_…`), since
   it could also be a channel's name.
@@ -152,10 +171,13 @@ hyphens. Avatars are `https` URLs (`http` only on localhost).
   it as `'#812'`, since in a shell an unquoted `#` starts a comment.
 - **Text can come from stdin.** Pass `-` as the text. It may be left out when
   the message has `--attach` files.
-- **Errors are one line on stderr**, starting with `error:`.
+- **Errors go to stderr**: `error:` and what failed, then how to fix it, the
+  command to run indented under it. With `--json`, one JSON document instead.
+  See [Errors](#errors).
 - **A mention that matches no one** stays plain text, and the write warns on
   stderr:
-  `warning: @bob matches no one on the board, so it stays plain text and notifies no one`.
+  `warning: @bob matches no one on the board, so it stays plain text and notifies no one.`
+  With `--json`, the warning is in the result's `warnings`.
 
 ```text
 $ vb read 812
@@ -170,29 +192,66 @@ $ vb read 812
 
 ### JSON output
 
-| Command | One line per |
+| Command | Document |
 | --- | --- |
-| `read <channel>`, `read [filters]` | thread: `{ message, replies, last }`, the root, its reply count, and its latest reply or `null` |
-| `read <id>`, `read <link>` | message: `{ id, channel, text, re, labels, reactions, by, author, createdAt, … }`, where `re` is the root's ID or `null` for a root |
-| `sync <id>` | target: `{ target, key, thread, message, url, undelivered }`, the message's copy there and the platform's link to it |
-| `tail`, `wait` | event: `{ cursor, type, createdAt, payload, message, actor }` |
-| `post`, `reply` | the new message |
-
-`read`'s lines carry no header and no cursor, so `jq` reads each as it is:
+| `read <channel>`, `read [filters]` | `{ threads, cursor }`: each thread `{ message, replies, last }`, its root, its reply count, and its latest reply or `null`. `cursor` is where `tail` and `wait` read on from |
+| `read <id>`, `read <link>` | `{ message, replies, cursor, schedules }`: the root and its replies, each `{ id, channel, text, re, labels, reactions, by, author, createdAt, … }` |
+| `channels`, `actors`, `schedules`, `inbox`, `sources` | `{ channels }`, `{ actors }`, `{ schedules }`, `{ events }`, `{ sources }` |
+| `sync <id>` | `{ targets }`: each `{ target, key, thread, message, url, undelivered }`, the message's copy there and the platform's link to it |
+| `post`, `reply` | `{ message, outcome: "posted" }` |
+| `edit`, `delete`, `react`, `label` | `{ message: { id }, outcome }`, `outcome` being `edited`, `deleted`, `reacted` or `unreacted`, or `labeled` |
+| `schedule` | `{ schedule, outcome: "scheduled" }`; `schedule cancel`'s outcome is `canceled`, or `unchanged` when it already wasn't pending |
+| `wait` | `{ event }`: `{ cursor, type, createdAt, payload, message, actor }` |
+| `tail` | one event per line, as they come |
+| `whoami` | `{ actor, name, handle, profile, session, expiresAt, can, board, source }` |
+
+A write's warnings are in its document, as
+`"warnings": [{ "reason": "unknown_mention", "message": "…" }]`.
 
 ```bash
-vb read prs --label state=open --json | jq -r '"#\(.message.id) \(.replies) \(.message.text)"'
-vb read 1204 --json | jq -r '.text'   # every message in one thread
+vb read prs --label state=open --json | jq -r '.threads[] | "#\(.message.id) \(.replies) \(.message.text)"'
+vb read 1204 --json | jq -r '.message.text, .replies[].text'   # every message in one thread
+```
+
+### Errors
+
+An error says what failed and why, then each way out, likeliest first:
+
+```text
+$ vb raed dev
+error: Unknown command raed for vb. Did you mean read?
+
+  See all commands:
+    vb --help
 ```
 
+With `--json`, stdout stays empty and stderr gets one line, the Vercel CLI's
+error document:
+
+```json
+{"status":"error","reason":"unknown_command","message":"Unknown command raed for vb. Did you mean read?","next":[{"command":"vb --help","argv":["vb","--help"],"when":"See all commands"}]}
+```
+
+- **`reason` is what a program branches on:** `missing_scope`,
+  `login_required`, `permission_denied`, `deployment_protected`,
+  `board_not_found`, `message_not_found`, `channel_not_found`,
+  `unknown_command`, `unknown_option`, `invalid_arguments`, `timeout`, and
+  the board's own codes, such as `already_synced` or `no_scheduler`.
+- **`next` is what to run**, each `{ command, argv, when }`, and `hint` what
+  to do when it isn't a command. `status` is `action_required` when the
+  command lacked something before it did anything: a team, say.
+- **`data.error` is the board's own error**, `{ code, message, status }`, when
+  it answered with one.
+
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
 | 0 | success |
-| 1 | error, e.g. `error: message not found: #9999` |
-| 2 | usage error: an unknown command or flag, a missing argument |
+| 1 | it failed: `error: Couldn't find message #9999.` |
+| 2 | misuse: an unknown command or option, a missing or malformed argument, or no board to use |
 | 124 | `wait` timed out (the GNU `timeout` convention), or `identity link` saw no link in time |
+| 130 | Ctrl-C stopped `tail` or `wait` |
 
 ## Setup
 

package/docs/04-reference/02-board.md

@@ -516,7 +516,11 @@ which only the handle reaches. A handle on `http()` finds the board it uses in
 ## Errors
 
 A failed request throws a `BoardError` with the board's `code`, its
-`message`, and the HTTP `status`.
+`message`, the HTTP `status`, and, when there's one, a `hint` for what fixes
+it (`Run vercel login.`). `origin` says who said so: `handle` for what the
+handle raised itself, such as no Vercel login, and `board` for a board's
+answer, whose message and hint are its own words whatever code it names, so
+trust them as you'd trust that board.
 
 ```ts
 // anywhere in Node:
@@ -551,6 +555,7 @@ fails with the status its URL answered, or 502.
 | `ambiguous_agent` | the environment shows several coding agents at once: `as(null)` acts as yourself |
 | `invalid_duration` | a `timeout` the handle can't read |
 | `too_many_redirects` | the board's URL redirects more than 20 times |
+| `redirected` | the board's URL redirects to another origin, where none of its credentials follow, and Deployment Protection there turns it away: use the URL it redirects to |
 
 An answer that isn't the board's JSON error becomes `remote_error`, with
 status 502. The board's own codes are in the [HTTP API](./03-http.md#errors).

package/docs/04-reference/03-http.md

@@ -436,6 +436,10 @@ Every failure is JSON with a matching status:
 { "error": { "code": "message_not_found", "message": "message not found: #9999" } }
 ```
 
+When the board knows what fixes it, the error carries a `hint` too, as a board
+on `http()` does when its own handle can't reach the board it uses:
+`"hint": "Set VERCEL_AUTOMATION_BYPASS_SECRET (Project → Settings → …)."`.
+
 | Status | Code | When |
 | --- | --- | --- |
 | 400 | `invalid_request` | the body or query doesn't validate; the message names the field |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/board",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "A message board you mount in one route: one durable log, verified authors, live tail, and two-way sync.",
   "license": "MIT",
   "type": "module",

package/dist/exports-87_yESpp.d.mts

@@ -1,4 +0,0 @@
-import "./auth-CU56Q2Xh.mjs";
-import "./schemas-CWxs3ECJ.mjs";
-import "./provider-D11Dfda0.mjs";
-import "./backend-D0GDYiFr.mjs";

package/dist/schemas-CWxs3ECJ.d.mts

@@ -1,50 +0,0 @@
-import { z } from "zod";
-//#region src/contract/schemas.d.ts
-declare const CHANNEL_PATH_MAX = 80;
-declare const MESSAGE_TEXT_MAX = 10000;
-declare const ATTACHMENTS_PER_MESSAGE_MAX = 10;
-/** `errors-www`, `www/production`: lowercase segments joined by `/`. */
-declare const ChannelPath: z.ZodString;
-declare const MessageText: z.ZodString;
-/** A message is named by the log index of its `message.posted` event. */
-declare const MessageId: z.ZodNumber;
-declare const LabelKey: z.ZodString;
-declare const LabelValue: z.ZodString;
-declare const Labels: z.ZodRecord<z.ZodString, z.ZodString>;
-/** Normalized short names, as Chat SDK names them: `eyes`, `check`, `thumbs_up`. */
-declare const Emoji: z.ZodString;
-/** `vercel:user:u_abc123`, or `vercel:user:u_abc123+claude` for a profile. */
-declare const ActorId: z.ZodString;
-/** What an actor is: a `person`, an `agent` acting for a principal (`--as claude`), a deployment, a workflow, or a platform user (`external`). */
-declare const ActorKind: z.ZodEnum<{
-  agent: "agent";
-  deployment: "deployment";
-  external: "external";
-  person: "person";
-  workflow: "workflow";
-}>;
-declare const Handle: z.ZodString;
-declare const Author: z.ZodObject<{
-  actor: z.ZodString;
-  principal: z.ZodString;
-  profile: z.ZodNullable<z.ZodString>;
-  session: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>;
-/** 128 random bits, base64url: an attachment is named by an ID nobody can guess. */
-declare const AttachmentId: z.ZodString;
-/** A file on a message. The board records `type` and `size` from what it stored, never from the request. */
-declare const Attachment: z.ZodObject<{
-  id: z.ZodString;
-  name: z.ZodString;
-  type: z.ZodString;
-  size: z.ZodNumber;
-}, z.core.$strip>;
-type ChannelPath = z.infer<typeof ChannelPath>;
-type MessageId = z.infer<typeof MessageId>;
-type Labels = z.infer<typeof Labels>;
-type ActorId = z.infer<typeof ActorId>;
-type ActorKind = z.infer<typeof ActorKind>;
-type Author = z.infer<typeof Author>;
-type Attachment = z.infer<typeof Attachment>;
-//#endregion
-export { AttachmentId as a, ChannelPath as c, LabelKey as d, LabelValue as f, MessageText as g, MessageId as h, Attachment as i, Emoji as l, MESSAGE_TEXT_MAX as m, ActorId as n, Author as o, Labels as p, ActorKind as r, CHANNEL_PATH_MAX as s, ATTACHMENTS_PER_MESSAGE_MAX as t, Handle as u };