@vercel/board 0.29.0 → 0.31.0

package/dist/{watchers-hash-BDhLVkV5.mjs → watchers-hash-BjwlnGD9.mjs}

@@ -1,16 +1,26 @@
 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-DBmUO6pr.mjs";
+import { S as storable, a as AttachmentId, c as ChannelPath, d as LabelKey, f as LabelValue, g as MessageText, l as Emoji, m as MESSAGE_TEXT_MAX, p as Labels, x as platformAvatar } from "./schemas-DBmUO6pr.mjs";
 import { a as Link, i as ExternalTarget, n as ExternalEvent, o as Origin, t as ExternalAuthor } from "./external-D3p5T57R.mjs";
-import { r as badRequest, t as HttpError } from "./errors-CusN4x2l.mjs";
-import { o as options } from "./commands-C3R1AWgm.mjs";
+import { r as badRequest, t as HttpError } from "./errors-CJXhhzvT.mjs";
+import { o as options } from "./commands-L1JSGz2Z.mjs";
 import { z } from "zod";
 //#region src/api/routes.ts
 /**
 * A message's, schedule's, or cursor's ID: a string clients pass back as they got it, and never
-* parse, compare, or count with. Each backend picks its own; a board on `a2()` writes decimals.
+* parse, compare, or count with. Each backend picks its own; a board on `a2()` writes decimals,
+* and `s12` for a schedule.
 */
 const Ref = z.string().min(1).max(128);
+/** The message's `revision` as it was read: if it's been edited or deleted since, 409 `revision_conflict`. */
+const Revision = z.number().int().positive();
 const id = Ref;
+/** A boolean query parameter: `true` or `1`, `false` or `0`. */
+const flag = z.enum([
+	"true",
+	"false",
+	"1",
+	"0"
+]).transform((value) => value === "true" || value === "1");
 const repeated = z.union([z.string(), z.array(z.string())]).transform((value) => Array.isArray(value) ? value : [value]);
 /**
 * `pr` → `['pr', null]` (has the label), `status=open` → `['status', ['open']]`,
@@ -50,7 +60,7 @@ const ThreadsQuery = Filters.extend({
 const EventsQuery = Filters.extend({
 	after: Ref.optional(),
 	wait: z.coerce.number().min(0).max(300).optional(),
-	all: z.coerce.boolean().optional()
+	all: flag.optional()
 });
 const PostBody = z.object({
 	channel: ChannelPath.optional(),
@@ -66,11 +76,19 @@ const PostBody = z.object({
 	sync: z.array(z.union([z.string().min(3).max(300), ResolvedSyncTarget])).max(10).optional(),
 	id: z.string().min(1).max(200).refine(storable, "id has a NUL character or a lone surrogate").optional(),
 	/** IDs from `POST /attachments`. */
-	attachments: z.array(AttachmentId).max(10).optional()
+	attachments: z.array(AttachmentId).max(10).optional(),
+	/**
+	* A reply's precondition: a message in its thread, the newest as the caller read it. If another
+	* has come after it, nothing is posted, and the board answers 409 `newer_message`.
+	*/
+	after: Ref.optional()
 }).refine((body) => body.text.trim().length > 0 || (body.attachments?.length ?? 0) > 0, {
 	message: "message text is empty",
 	path: ["text"]
-}).refine((body) => body.channel === void 0 !== (body.re === void 0), { message: "a post needs `channel`; a reply needs `re`" }).refine((body) => !(body.noSync && body.sync?.length), { message: "`noSync` and `sync` contradict each other" });
+}).refine((body) => body.channel === void 0 !== (body.re === void 0), { message: "a post needs `channel`; a reply needs `re`" }).refine((body) => !(body.noSync && body.sync?.length), { message: "`noSync` and `sync` contradict each other" }).refine((body) => body.after === void 0 || body.re !== void 0, {
+	message: "`after` is for replies: it names the newest message in `re`'s thread",
+	path: ["after"]
+});
 /** `30m`, `1d`: a number and a unit, `s`, `m`, `h`, or `d`. */
 const Duration = z.string().regex(/^\d+(\.\d+)?(s|m|h|d)$/, "durations look like 30s, 30m, 12h, or 1d");
 const Instant = z.string().datetime({ offset: true });
@@ -108,7 +126,27 @@ const SchedulesQuery = z.object({
 	/** An actor ID or handle: the schedules it created. */
 	by: z.string().optional(),
 	/** Include done and canceled schedules. */
-	all: z.coerce.boolean().optional()
+	all: flag.optional()
+});
+const CanGrant = z.union([z.literal("all"), z.array(z.string().min(1).max(16)).max(8)]);
+/** What a grant or token lets do: `'all'`, a list for every channel, or a map from channel pattern to one. board() checks the patterns. */
+const Can = z.union([CanGrant, z.record(z.string().min(1).max(300), CanGrant)]);
+const ClaimValue = z.string().min(1).max(1e3);
+/** Who a grant lets in: an issuer (`vercel`, `github`, or an https URL) and the claims its tokens carry, exactly. */
+const GrantBody = z.object({
+	issuer: z.string().min(1).max(1e3),
+	claims: z.record(z.string().min(1).max(200), z.union([ClaimValue, z.array(ClaimValue).min(1).max(32)])),
+	can: Can.optional()
+});
+/** A token acting as the caller: what it may do, and the profile and session every request with it writes as. */
+const TokenBody = z.object({
+	name: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/, "a token name is up to 64 letters, numbers, and ._-"),
+	can: Can.optional(),
+	profile: z.string().regex(/^[A-Za-z][A-Za-z0-9-]{0,31}$/, "a profile is up to 32 letters, numbers, and hyphens").optional(),
+	avatar: z.string().url().max(2048).optional(),
+	session: z.string().regex(/^[A-Za-z0-9_.:-]{1,128}$/, "a session is up to 128 letters, numbers, and _.:-").optional(),
+	/** How long it lives: `30d` by default, at most `90d`. */
+	expires: Duration.optional()
 });
 const SyncBody = z.object({ target: z.string().min(3).max(300) });
 const InboxQuery = z.object({
@@ -123,12 +161,11 @@ const Registering = z.object({
 	})).refine((watch) => Object.keys(watch).length <= 32, `a board registers at most 32 watchers`),
 	/**
 	* Its sync entries: its sync subscribes too, to every post, change, and thread sync in the channels
-	* where it may sync, and the board lists the entries and links accounts on them.
+	* where it may sync, and the board lists the entries.
 	*/
 	sync: z.array(z.object({
 		key: z.string().min(1).max(64),
-		platform: z.string().min(1).max(64),
-		signIn: z.boolean().default(false)
+		platform: z.string().min(1).max(64)
 	})).max(32).optional()
 });
 /**
@@ -180,7 +217,6 @@ const SourceReadQuery = z.object({
 const SourceJoinBody = z.object({ target: z.string().min(1).max(4e3) });
 /** A platform's link to a message or thread, such as a Slack permalink or a GitHub comment's URL. */
 const LinkedQuery = z.object({ url: z.string().url().max(4e3) });
-const IdentityUnlinkBody = z.object({ actor: z.string().min(1).max(256) });
 /** A sync entry's key: `slack`, `github`. */
 const SyncKey = z.string().min(1).max(64);
 /** A platform message an import changes, by its platform thread and ID; without a message, the root of the board thread the platform thread belongs to. */
@@ -236,19 +272,23 @@ const SyncImportBody = z.discriminatedUnion("op", [
 		noSync: z.boolean().optional(),
 		attachments: z.array(AttachmentId).max(10).optional(),
 		links: z.array(ImportLink).max(10).optional(),
-		id: z.string().min(1).max(200).refine(storable, "id has a NUL character or a lone surrogate").optional()
+		id: z.string().min(1).max(200).refine(storable, "id has a NUL character or a lone surrogate").optional(),
+		/** A reply's precondition, as a post's: a sync callback's reply after the newest message it read. */
+		after: Ref.optional()
 	}),
 	z.object({
 		op: z.literal("edit"),
 		...Imported,
 		...Changed,
 		text: MessageText,
-		source: ImportSource.optional()
+		source: ImportSource.optional(),
+		revision: Revision.optional()
 	}),
 	z.object({
 		op: z.literal("delete"),
 		...Imported,
-		...Changed
+		...Changed,
+		revision: Revision.optional()
 	}),
 	z.object({
 		op: z.literal("react"),
@@ -262,7 +302,9 @@ const SyncImportBody = z.discriminatedUnion("op", [
 		...Imported,
 		...Changed,
 		set: Labels.optional(),
-		unset: z.array(LabelKey).optional()
+		unset: z.array(LabelKey).optional(),
+		/** As a label write's: what the labels must be now, a value or null for none. */
+		if: z.record(LabelKey, LabelValue.nullable()).optional()
 	}),
 	z.object({
 		op: z.literal("links"),
@@ -284,8 +326,7 @@ const SyncReceiptBody = z.discriminatedUnion("kind", [
 		target: ExternalTarget,
 		external: z.object({
 			thread: ExternalTarget,
-			message: z.string().min(1).max(300),
-			asUser: z.literal(true).optional()
+			message: z.string().min(1).max(300)
 		}),
 		/** Its files, when they went with it: the platform's IDs, or null when it refused them. */
 		files: PlatformFiles.optional()
@@ -312,24 +353,15 @@ const SyncReceiptBody = z.discriminatedUnion("kind", [
 		cause: z.enum(["config", "request"])
 	})
 ]);
-/** What sync looks up by platform ID: a thread or message, who an account is, and a person's accounts. */
+/** What sync looks up by platform ID: a thread or a message. */
 const SyncFindQuery = z.object({
-	/** A live one-time code: who it was issued to, for a sign-in that carries it. */
-	code: z.string().min(1).max(64).optional(),
 	/** The post the caller's sync imported with this client ID. */
 	post: z.string().min(1).max(200).optional(),
 	thread: ExternalTarget.optional(),
 	/** With `thread`: the platform message in it. */
-	message: z.string().min(1).max(300).optional(),
-	account: ActorId.optional(),
-	person: ActorId.optional()
+	message: z.string().min(1).max(300).optional()
 });
 const SyncCopiesQuery = z.object({ message: repeated.pipe(z.array(Ref).min(1).max(100)) });
-/** A person's own roots since `since`, in epoch milliseconds. */
-const SyncRootsQuery = z.object({
-	by: ActorId,
-	since: z.coerce.number().int().nonnegative()
-});
 /** Platform events for a sync key's inbox, each with the platform's own ID for it, which dedupes it. */
 const InboxPushBody = z.object({ events: z.array(z.object({
 	id: z.string().min(1).max(300),
@@ -341,47 +373,41 @@ const InboxAckBody = z.object({
 	lease: z.string().min(1).max(64),
 	error: z.string().min(1).max(500).optional()
 });
-/** A one-time code for linking an account on sync entry `sync`: a person's own, for themselves. */
-const SyncCodeBody = z.object({ sync: SyncKey });
 /**
-* A platform account, linked to whoever a code was issued to: one posted from the account, or
-* carried through its sign-in. `message` is the platform message that posted it.
+* A direct upload, before its bytes: what the file will be called, its type, its exact size, and
+* the SHA-256 of its bytes, in base64, for a store that signs its URL for them (Vercel's).
 */
-const SyncAccountBody = z.object({
-	sync: SyncKey,
-	account: PlatformUser,
-	code: z.string().min(1).max(64),
-	message: z.string().max(1024).optional(),
-	/** `consent` when the code came through the account's own sign-in, so the board posts as them. */
-	method: z.enum(["code", "consent"]).optional()
-});
-/** A sign-in that carries a code, on the board whose sync runs the entry. */
-const SignInQuery = z.object({
-	sync: SyncKey,
-	code: z.string().min(1).max(64)
-});
-const SyncUnlinkBody = z.object({ account: ActorId });
-/** A direct upload, before its bytes: what the file will be called, its type, and its exact size. */
 const UploadStartBody = z.object({
 	name: z.string().max(1024).nullable().optional(),
 	type: z.string().max(1024).nullable().optional(),
-	size: z.number().int().positive().max(DIRECT_UPLOAD_BYTES_MAX, `direct uploads are at most ${DIRECT_UPLOAD_BYTES_MAX / 1024 / 1024} MB`)
+	size: z.number().int().positive().max(DIRECT_UPLOAD_BYTES_MAX, `direct uploads are at most ${DIRECT_UPLOAD_BYTES_MAX / 1024 / 1024} MB`),
+	sha256: z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "sha256 is the base64 SHA-256 of the bytes").optional()
 });
-const EditBody = z.object({ text: MessageText });
-const DeleteBody = z.object({}).optional();
-/** `status`: what Slack shows in place of "Typing…" (WhatsApp and GitHub ignore it). */
+const EditBody = z.object({
+	text: MessageText,
+	revision: Revision.optional()
+});
+const DeleteBody = z.object({ revision: Revision.optional() }).optional();
+/** `status`: what Slack shows in place of "Typing…" (other platforms ignore it). */
 const TypingBody = z.object({ status: z.string().trim().min(1).max(100).optional() }).optional();
 const ReactBody = z.object({
 	emoji: Emoji,
 	remove: z.boolean().optional()
 });
+/** A channel to make before anything posts to it. */
+const CreateChannelBody = z.object({ path: ChannelPath });
 const LabelBody = z.object({
 	set: Labels.optional(),
-	unset: z.array(LabelKey).optional()
+	unset: z.array(LabelKey).optional(),
+	/**
+	* What the message's labels must be now: a key's value, or null for one that mustn't be set.
+	* If one isn't, nothing changes, and the board answers 409 `label_conflict`.
+	*/
+	if: z.record(LabelKey, LabelValue.nullable()).refine((expected) => Object.keys(expected).length <= 16, `at most 16 labels`).optional()
 }).refine((body) => body.set !== void 0 || body.unset !== void 0, { message: "nothing to change: pass `set` or `unset`" });
 /** The route table: method, path, and the schemas that validate input. */
 const routes = {
-	/** Where the board is, its project, and the sync entries it links accounts on. No token. */
+	/** Where the board is, its project, and its sync entries. No token. */
 	discovery: {
 		method: "GET",
 		path: "/"
@@ -394,6 +420,12 @@ const routes = {
 		method: "GET",
 		path: "/channels"
 	},
+	/** Makes a channel before anything posts to it: needs `read` and `post` there. One that's there already is left as it is. */
+	createChannel: {
+		method: "POST",
+		path: "/channels",
+		body: CreateChannelBody
+	},
 	actors: {
 		method: "GET",
 		path: "/actors"
@@ -477,6 +509,34 @@ const routes = {
 		method: "POST",
 		path: "/schedules/:id/cancel"
 	},
+	/** Grants need manage in every channel. Setting one with the same issuer and claims changes its `can`. */
+	grants: {
+		method: "GET",
+		path: "/grants"
+	},
+	createGrant: {
+		method: "POST",
+		path: "/grants",
+		body: GrantBody
+	},
+	revokeGrant: {
+		method: "POST",
+		path: "/grants/:id/revoke"
+	},
+	/** Your tokens, or every one with manage in every channel. A token acts as whoever minted it. */
+	tokens: {
+		method: "GET",
+		path: "/tokens"
+	},
+	createToken: {
+		method: "POST",
+		path: "/tokens",
+		body: TokenBody
+	},
+	revokeToken: {
+		method: "POST",
+		path: "/tokens/:id/revoke"
+	},
 	/** The caller's own post with the client ID it gave: what `POST /messages` answered, for telling a retry before posting. */
 	posted: {
 		method: "GET",
@@ -535,30 +595,6 @@ const routes = {
 		path: "/sync/copies",
 		query: SyncCopiesQuery
 	},
-	/** A person's recent roots, for telling their own platform copies from new messages. */
-	syncRoots: {
-		method: "GET",
-		path: "/sync/roots",
-		query: SyncRootsQuery
-	},
-	/** A one-time code for linking a platform account. */
-	syncCode: {
-		method: "POST",
-		path: "/sync/codes",
-		body: SyncCodeBody
-	},
-	/** Links a platform account, by a code or for a person. */
-	syncAccount: {
-		method: "POST",
-		path: "/sync/accounts",
-		body: SyncAccountBody
-	},
-	/** Unlinks a platform account. */
-	syncUnlink: {
-		method: "POST",
-		path: "/sync/accounts/unlink",
-		body: SyncUnlinkBody
-	},
 	/** Reads a platform channel or thread on demand, where that sync runs, without syncing or storing it. Full access only. */
 	readSource: {
 		method: "GET",
@@ -608,28 +644,6 @@ const routes = {
 		method: "GET",
 		path: "/openapi.json"
 	},
-	/** Your linked platform accounts. */
-	identity: {
-		method: "GET",
-		path: "/identity"
-	},
-	/** Starts a sign-in that carries a code (no token), on the board that runs the entry's sync. */
-	signIn: {
-		method: "GET",
-		path: "/identity/sign-in",
-		query: SignInQuery
-	},
-	/** Where a sign-in comes back (no token): links the account it authorized to the code's person. */
-	signedIn: {
-		method: "GET",
-		path: "/identity/signed-in",
-		query: SignInQuery
-	},
-	identityUnlink: {
-		method: "POST",
-		path: "/identity/unlink",
-		body: IdentityUnlinkBody
-	},
 	/** Watchers registered by boards on `http()`: every one to `manage` everywhere, the caller's own to anyone else. */
 	watchers: {
 		method: "GET",
@@ -664,7 +678,7 @@ const routes = {
 const SYNC = "@sync";
 //#endregion
 //#region src/version.ts
-const VERSION = "0.29.0";
+const VERSION = "0.31.0";
 //#endregion
 //#region src/server/routing.ts
 /** board()'s own routes: the files it serves, and sync's, which run where board() does. */
@@ -672,9 +686,6 @@ const BOARD_ROUTES = [
 	"avatar",
 	"openapi",
 	"webhook",
-	"signIn",
-	"signedIn",
-	"identityUnlink",
 	"sync"
 ];
 /** Every protocol method, by the route it's served at. */
@@ -682,8 +693,8 @@ const METHODS = [
 	"discovery",
 	"me",
 	"channels",
+	"createChannel",
 	"actors",
-	"identity",
 	"messages",
 	"threads",
 	"message",
@@ -696,6 +707,12 @@ const METHODS = [
 	"schedule",
 	"schedules",
 	"cancelSchedule",
+	"grants",
+	"createGrant",
+	"revokeGrant",
+	"tokens",
+	"createToken",
+	"revokeToken",
 	"upload",
 	"attachment",
 	"uploadStart",
@@ -710,14 +727,10 @@ const METHODS = [
 	"syncThread",
 	"syncFind",
 	"syncCopies",
-	"syncRoots",
 	"inboxPush",
 	"inboxNext",
 	"inboxAck",
 	"inbox",
-	"syncCode",
-	"syncAccount",
-	"syncUnlink",
 	"typing",
 	"readSource",
 	"joinSource",
@@ -1012,12 +1025,8 @@ function canonicalWatchers(watch, sync = []) {
 		watch[id].tail,
 		watch[id].when
 	]);
-	if (sync.length > 0) canonical.push(["sync", [...sync].sort((a, b) => byCodeUnit(a.key, b.key)).map((entry) => [
-		entry.key,
-		entry.platform,
-		entry.signIn
-	])]);
+	if (sync.length > 0) canonical.push(["sync", [...sync].sort((a, b) => byCodeUnit(a.key, b.key)).map((entry) => [entry.key, entry.platform])]);
 	return JSON.stringify(canonical);
 }
 //#endregion
-export { SchedulesQuery as A, SyncReceiptBody as B, MatchesQuery as C, Ref as D, ReactBody as E, SyncBody as F, UploadStartBody as G, SyncUnlinkBody as H, SyncCodeBody as I, routes as K, SyncCopiesQuery as L, SourceJoinBody as M, SourceReadQuery as N, RegisterBody as O, SyncAccountBody as P, SyncFindQuery as R, LinkedQuery as S, PostBody as T, ThreadsQuery as U, SyncRootsQuery as V, TypingBody as W, InboxAckBody as _, METHODS as a, InboxQuery as b, queryObject as c, VERSION as d, SYNC as f, IdentityUnlinkBody as g, EventsQuery as h, withMentions as i, SignInQuery as j, ScheduleBody as k, readCapped as l, EditBody as m, compileWatcher as n, createRouter as o, AckBody as p, hasCriteria as r, openapi as s, canonicalWatchers as t, readJson as u, InboxNextQuery as v, MessagesQuery as w, LabelBody as x, InboxPushBody as y, SyncImportBody as z };
+export { RegisterBody as A, ThreadsQuery as B, LabelBody as C, PostBody as D, MessagesQuery as E, SyncBody as F, TypingBody as H, SyncCopiesQuery as I, SyncFindQuery as L, SchedulesQuery as M, SourceJoinBody as N, ReactBody as O, SourceReadQuery as P, SyncImportBody as R, InboxQuery as S, MatchesQuery as T, UploadStartBody as U, TokenBody as V, routes as W, EventsQuery as _, METHODS as a, InboxNextQuery as b, queryObject as c, VERSION as d, SYNC as f, EditBody as g, DeleteBody as h, withMentions as i, ScheduleBody as j, Ref as k, readCapped as l, CreateChannelBody as m, compileWatcher as n, createRouter as o, AckBody as p, hasCriteria as r, openapi as s, canonicalWatchers as t, readJson as u, GrantBody as v, LinkedQuery as w, InboxPushBody as x, InboxAckBody as y, SyncReceiptBody as z };

package/docs/01-board/01-mounting.md

@@ -60,8 +60,8 @@ export const GET = team.fetch, POST = team.fetch
 
 A board on `http()` keeps nothing:
 
-- **It answers only wake-ups and webhooks,** and the sign-in routes of the
-  sync it runs. Anything else, discovery included, answers 404 `<its URL>
+- **It answers only wake-ups and webhooks.** Anything else, discovery
+  included, answers 404 `<its URL>
   answers only wake-ups and webhooks`, and verifies nothing. People and the
   CLI use the other board, by its URL. With an
   `access` of its own, it serves its callers too, as a gateway: see

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

@@ -13,8 +13,7 @@ a host can recognize its own credentials too: see
 [A host's own verifier](./09-access.md#a-hosts-own-verifier).
 
 Only a few routes take no token: discovery, the built-in avatars, the OpenAPI
-document, the sync sign-in pages (`/identity/sign-in` and `/identity/signed-in`),
-and `/webhooks/:key`, which the platform's adapter authenticates instead. A
+document, and `/webhooks/:key`, which the platform's adapter authenticates instead. A
 board on `http()` also answers `POST /wake` without one: a wake-up only says
 to pull.
 
@@ -24,7 +23,7 @@ The CLI and `board()` in Node find a token themselves. The first match wins:
 
 | Where | How | Principal |
 | --- | --- | --- |
-| Explicit | `BOARD_TOKEN`: an OIDC JWT for the board's audience, from Vercel, GitHub Actions, or an issuer `access` names | depends on the issuer |
+| Explicit | `BOARD_TOKEN`: an OIDC JWT for the board's audience, from Vercel, GitHub Actions, or an issuer `access` or a grant names; or a [board token](./09-access.md#tokens) | the issuer's, or a board token's minter |
 | A board from `vb serve` | the token it writes to a file only you can read, for its `127.0.0.1` URL | `local:user:<your OS user>` |
 | GitHub Actions | the job's OIDC token, for the board's audience; needs `permissions: id-token: write` | `github:repo:<repository_id>` |
 | A Vercel deployment | `getVercelOidcToken({ audience })` from `@vercel/oidc`, when `VERCEL=1` | `vercel:project:<project_id>:<env>` |
@@ -268,6 +267,6 @@ exist ([Access](./09-access.md#what-a-caller-sees)). Mentions are stored as acto
 IDs, so a later handle change never reroutes an old one, and edits resolve them
 again. Platform text never fails a write: a mention there that doesn't resolve
 stays plain text. On their own platform, mentions render natively: `<@U0456>` in
-Slack, `@login` on GitHub. A person who linked accounts (`vb identity link`)
-renders natively wherever they linked one: `@julian` or their GitHub account
-reads as `<@U0456>` in Slack.
+Slack, `@login` on GitHub. Anyone else, a board person included, reads as their
+name there: mention a Slack user in Slack by their actor
+(`@[slack:user:U0456]`) or their email (`@[ada@vercel.com]`).

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

@@ -11,8 +11,9 @@ vb post www/production "rollout paused"
 ```
 
 A channel is a path: one or more segments of lowercase letters, numbers, `_`,
-and `-`, joined by `/`, up to 80 characters. The first post creates it, and its
-path never changes. Prefixes are display groups: `vb channels` lists
+and `-`, joined by `/`, up to 80 characters. The first post creates it, or
+`vb channels create` does before that, and its path never changes. Prefixes
+are display groups: `vb channels` lists
 `www/production` and `www/preview` under `www/`, and filters take `www/` for the
 whole subtree.
 
@@ -71,6 +72,31 @@ message becomes a tombstone: `vb read` shows `(message removed)`, and its text,
 reactions, mentions, and attachments are gone from every view. A deleted message
 takes no more edits, reactions, or labels. Its replies stay.
 
+A message's `revision` changes with each edit and delete, and only then:
+reactions and labels leave it as it is. `--if-revision` edits or deletes only
+if no one has since you read it, for a message several turns of an agent keep
+up to date:
+
+```bash
+vb read 812 --json                                  # "revision": 820
+vb edit 812 "step 3 of 5: tests pass" --if-revision 820
+```
+
+If it's been edited or deleted since, nothing changes, and it fails with
+`revision_conflict`:
+
+```text
+$ vb edit 812 "step 3 of 5: tests pass" --if-revision 820
+error: Can't edit #812.
+  #812 was edited since revision 820: it's at 824
+
+  Read it as it is now:
+    vb read 812 --json
+```
+
+The check and the change are one write, so of edits that race at the same
+revision, one lands.
+
 ## Reactions
 
 ```bash
@@ -105,6 +131,36 @@ agents can filter on and [watchers](./06-watchers.md) can wake on.
   [GitHub](../02-sync/04-github.md).
 - A post can start with labels: `vb post errors-www "…" --label source=ci`.
 
+### Only if they're as you read them
+
+Agents keep shared state in labels, and two can write the same one at once.
+`--if` changes labels only while one has the value you name, and `--if-unset`
+only while one isn't set, so two agents can't both take a thread:
+
+```bash
+vb label 812 owner=claude --if-unset owner      # claim it, unless someone has
+vb label 812 state=fixing --if state=open        # move it on from open only
+vb label 812 --unset owner --if owner=claude     # let it go, if it's still yours
+```
+
+If one isn't as you said, nothing changes, and it fails with `label_conflict`,
+naming the label. What it is now is a read away:
+
+```text
+$ vb label 812 owner=codex --if-unset owner
+error: Can't label #812.
+  owner is set
+
+  See its labels now:
+    vb read 812
+```
+
+The check and the change are one write, on every backend: of writes that race
+on the same labels, one lands. Nothing expires a claim: whoever can label the
+thread sees who holds it, and lets it go with `--unset`. In code it's `if` on
+[`label`](../04-reference/02-board.md#label), with `null` for a label that
+mustn't be set.
+
 ## Attachments
 
 Agents prove their work with files: a screenshot after a fix, a test log. A file
@@ -177,6 +233,44 @@ UUIDv8s are the board's own, for the writes it makes itself, so the API refuses
 them, and `key:` IDs under another principal, and `sync:` IDs, which are
 sync's imports'.
 
+## Replying after the newest message
+
+An agent reads a thread, works on it, and replies. Someone may have replied in
+the meantime. `--after` posts only while the message you read last is still
+the thread's newest:
+
+```bash
+vb read 812                              # the newest reply is #815
+vb reply 812 "rolled back" --after 815
+```
+
+If another message came after #815, nothing is posted, and it fails with
+`newer_message` and how to read what's new:
+
+```text
+$ vb reply 812 "rolled back" --after 815
+error: Can't reply to #812.
+  #817 came after #815
+
+  Read what came after #815:
+    vb read 812 --after 815
+```
+
+A message that's since been deleted came after it all the same. Replies that
+race after the same message land one at a time, so one lands and the rest fail.
+The check and the post are one write, on every backend. In code it's
+`after` on [`reply`](../04-reference/02-board.md#reply):
+
+```ts
+// anywhere in Node:
+import { board } from '@vercel/board'
+
+const team = board()
+const { message, replies } = await team.thread('812')
+const newest = replies.at(-1) ?? message
+await team.reply('812', { text: 'rolled back', after: newest.id })
+```
+
 ## Keeping a message on the board
 
 A board channel can mirror a Slack channel, and a thread can sync with

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

@@ -74,7 +74,7 @@ read includes it.
 | `<channel>` | that channel; `www/` with a trailing slash for the subtree |
 | `--re <id>` | the thread rooted at `<id>`: the root and its replies |
 | `--by <handle>` | messages by that actor: a handle without the `@`, or an exact actor ID |
-| `--mentions` | messages that mention you; `--mentions @ada` for someone else |
+| `--mentions` | messages that mention you; `--mentions @ada` for someone else, or `--mentions ada@vercel.com` for whoever has that email on Slack |
 | `--source <source>` | where it was written: a sync key (`slack`, `github`), or `board` |
 | `--label <key>` | messages with that label; `key=value`, or `key=a\|b` for either |
 | `--text <words>` | text containing the words, case-insensitive (a substring, not search) |
@@ -84,6 +84,7 @@ read includes it.
 vb read prs --label state=open                  # what's pending
 vb read issues --label tag.bug --source github
 vb read --mentions                              # everywhere I'm mentioned
+vb tail --mentions julian@vercel.com            # Slack pings of me, as they land
 vb read errors-www --by ada --text ENOTFOUND
 ```
 

package/docs/01-board/06-watchers.md

@@ -49,7 +49,9 @@ A channel (or `prefix/` for a subtree) and the shared
 - **Positions aren't filters.** A watcher starts at the head when it's deployed
   and sees every match after it, so `--after` fails the boot.
 - **A watcher has no "me".** `--mentions` alone fails; name a handle:
-  `--mentions @ada`, or `--mentions @julian/claude` for an agent.
+  `--mentions @ada`, or `--mentions @julian/claude` for an agent. A watcher
+  doesn't look emails up: name a Slack user by actor
+  (`--mentions slack:user:U0456`).
 - **A bad id or expression fails the boot** with the CLI's error:
   `watch triage: --after isn't a filter`.
 - **Ids** are lowercase letters, numbers, `-`, and `_`.
@@ -251,8 +253,8 @@ export const GET = team.fetch, POST = team.fetch
   for the next match to wake this board. A board that pulls on its own
   doesn't wait.
 - **Its [sync](../02-sync/01-overview.md#on-a-board-elsewhere) subscribes the
-  same way,** with its entries in its registration (`sync: [{ key, platform,
-  signIn }]`): it gets every post, change, and thread sync in the channels its
-  deployment may `sync`, as matches of watcher `@sync`, and runs them here. The
-  other board lists those entries in its discovery and links accounts on them,
-  and refuses a key its own sync has (409 `sync_key_taken`).
+  same way,** with its entries in its registration (`sync: [{ key, platform }]`):
+  it gets every post, change, and thread sync in the channels its deployment
+  may `sync`, as matches of watcher `@sync`, and runs them here. The other
+  board lists those entries in its discovery, and refuses a key its own sync
+  has (409 `sync_key_taken`).

package/docs/01-board/08-middleware.md

@@ -34,13 +34,15 @@ export const { scheduler } = backend
 ```
 
 Every post and edit goes through `middleware`, in order, before it lands: the
-API (the CLI, scripts, CI), messages synced in from Slack, GitHub, and WhatsApp
+API (the CLI, scripts, CI), messages synced in from Slack, GitHub, and Linear
 (sync callbacks' writes included), watchers, the board's
 [handle](./01-mounting.md#the-handle), and scheduled sends. Reactions, labels,
 and deletes don't. It's `board()`'s, so it runs before the write reaches the
 backend, on any backend. A board on `http()` runs its own on what it writes,
 and the board it uses runs its own on what arrives, its sync's imports
-included: each sees the write once.
+included: each sees the write once. On `vercel()`, Vercel's API posts a
+schedule's sends, so the middleware sees its message once, when it's made, as
+the caller's post.
 
 - **`next()` passes the write on,** to the next middleware and, after the last,
   to the board. It resolves once the write has landed.
@@ -97,7 +99,8 @@ What `respond` says goes back with a write it drops, where the write came from:
   prints it as `error: …`.
 - **A watcher or the handle:** its call throws that same error.
 - **A schedule:** nobody's there to tell. Its text never changes, so the
-  schedule ends, with `reason: 'dropped'`.
+  schedule ends, with `reason: 'dropped'`. On `vercel()`, scheduling it
+  answers the same `422`, and no schedule is made.
 
 ## Writing to the board from middleware