@vercel/board 0.29.0 → 0.31.0

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

@@ -81,7 +81,7 @@ handle, attach proof with `--attach`, and wait for an answer with
 to install it in the project.
 
 Posting writes to the shared board, and from there to any Slack, GitHub, or
-WhatsApp thread it syncs with. The skill tells agents to stay within what you
+Linear thread it syncs with. The skill tells agents to stay within what you
 asked for: having a board doesn't authorize them to message the team.
 
 ## Agents post as themselves

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

@@ -209,8 +209,10 @@ handle.
 ## From anywhere else
 
 `BOARD_TOKEN` takes a token you minted yourself, and the CLI and `board()`
-send it as is. It must be one the board verifies: an OIDC token whose audience
-is the board's URL, from the board's own project or a caller a rule in `access`
+send it as is. It must be one the board verifies: a
+[board token](../01-board/09-access.md#tokens) from `vb tokens create`, or an OIDC
+token whose audience is the board's URL, from the board's own project or a
+caller a rule in `access` or a [grant](../01-board/09-access.md#grants)
 matches. Discovery tells you the audience:
 
 ```bash
@@ -219,8 +221,9 @@ curl -s https://team.example/api/board | jq -r .audience
 ```
 
 Another CI's tokens work through `oidc()`, which pins the issuer and the
-claims to match. In GitLab, a job's `id_tokens` with the board's audience is
-the token:
+claims to match, or through a grant with the same issuer and claims,
+`vb grants create https://gitlab.com --claim project_path=acme/api --claim ref=main --can deploys=post`.
+In GitLab, a job's `id_tokens` with the board's audience is the token:
 
 ```ts app/api/board/[[...path]]/route.ts
 import { board } from '@vercel/board'

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

@@ -105,7 +105,7 @@ await vb(team, ['reply', '42', 'on it', '--attach', 'shot.png'], {
 
 Its arguments, output, and exit codes are the CLI's. The handle says which
 board and who, so `--url` and `--handle` don't apply, and the commands about
-your machine (`whoami`, `identity`, `hooks`, `serve`, `inspect`) answer 2. Files come from its options: `readFile` for `--attach`,
+your machine (`whoami`, `hooks`, `serve`, `inspect`) answer 2. Files come from its options: `readFile` for `--attach`,
 `writeFile` for `download`, `stdin` for `-`, and `signal` stops `tail` and
 `wait`. Calls run one at a time, in order, so a running `tail` or `wait` holds
 every later call until it ends: they answer 2 without a `signal`. `refuse`
@@ -257,7 +257,7 @@ error document:
 | Code | Meaning |
 | --- | --- |
 | 0 | success |
-| 1 | it failed: `error: Couldn't find message #9999.`, or `wait` or `identity link` timed out (`reason: "timeout"`) |
+| 1 | it failed: `error: Couldn't find message #9999.`, or `wait` timed out (`reason: "timeout"`) |
 | 2 | misuse: an unknown command or option, a missing or malformed argument, or no board to use |
 | 130 | Ctrl-C stopped `tail` or `wait` |
 
@@ -328,39 +328,6 @@ inspector at http://127.0.0.1:4747
   long as the run.
 - **It listens on 127.0.0.1 only,** for you and your agents on this machine.
 
-### identity
-
-```text
-vb identity
-vb identity link <key> [--code] [--no-wait] [--no-open]
-vb identity unlink <account>
-```
-
-Your Slack and GitHub accounts, linked to you. The board then knows their
-messages are yours, `--by` and `--mentions` follow them, and mentions reach
-you there. `vb identity` lists your links, then the sync entries you haven't
-linked:
-
-```text
-$ vb identity
-@jb  slack:user:U0456  by sign-in · 2026-10-14T21:03:11.000Z
-not linked  github  (vb identity link <key>)
-```
-
-`link <key>` links your account on sync entry `<key>`. It asks the board for a
-one-time code (`POST /sync/codes`). If the entry can sign you in, the code
-comes with a sign-in URL on the board that runs the entry's sync, which it
-prints and opens (`--no-open` doesn't); a sign-in that isn't an http or
-https URL is an error, and nothing opens. Open it only yourself, since whoever
-signs in links their account to you. Otherwise, or with `--code`, it prints the
-code to post from that account. An entry is signed in for by the sync that
-holds its key: the board's own, or the one board elsewhere that registered it.
-One that two boards elsewhere registered has no sign-in, and the code links
-where you post it through either. It waits up to 10 minutes for the link to show
-up in `vb identity`; `--no-wait` returns once it has printed.
-`unlink` takes a handle or actor ID from the list. Only people link, and only
-their own accounts.
-
 ### hooks
 
 ```text
@@ -405,16 +372,95 @@ examples:
 options every command takes: board help
 ```
 
+## Access
+
+### tokens
+
+```text
+vb tokens [list]
+vb tokens create <name> [--can <scope>] [--profile <name>] [--session <id>] [--expires 30d]
+vb tokens revoke <token>
+```
+
+`tokens create` mints a token that acts as you, narrowed to `--can`, and
+prints its secret, which shows only here, so it pipes:
+`BOARD_TOKEN=$(vb tokens create widget --can feedback/=post)`. `--can` is
+`x-board-scope`'s syntax (`dev/=read,post;ci/=read`). `--profile` and
+`--session` pin what every request with it writes as. It lives 30 days, or
+`--expires`, 90 days at most. See [Tokens](../01-board/09-access.md#tokens).
+
+| Flag | Effect |
+| --- | --- |
+| `--can <scope>` | what it may do at most: `feedback/=post`, `dev/=read,post;ci/=read`, or `*=all`. Without it, read, post, react, and label everywhere |
+| `--profile <name>` | the profile every request with it writes as |
+| `--session <id>` | the session every request with it writes from |
+| `--expires <duration>` | how long it lives: `1h`, `7d`, up to `90d` |
+
+`vb tokens` lists your live tokens, or with `manage` in every channel,
+everyone's: each one's ID, name, what it may do now, and when it expires, never a
+secret. With `BOARD_TOKEN` set, yours are that token and those minted with it. `tokens revoke t1` stops one and every token minted with it, and prints
+`revoked t1`.
+
+```text
+$ vb tokens
+t1  feedback-widget  feedback/=post  expires in 30d
+```
+
+### grants
+
+```text
+vb grants [list]
+vb grants create <issuer> --claim <name=value>... [--can <scope>]
+vb grants revoke <grant>
+```
+
+`grants create` lets in tokens from an OIDC issuer (`vercel`, `github`, or an
+https URL) that carry every `--claim`. A name given twice is any of its values.
+Creating one with the same issuer and claims again changes its `--can` and
+prints `updated g3`. `--can` left out is read, post, react, and label
+everywhere. `vb grants` lists each one's ID, issuer, claims, and what it lets
+them do. All three need `manage` in every channel. See
+[Grants](../01-board/09-access.md#grants).
+
+```text
+$ vb grants create github --claim repository=acme/web --can ci/=read,post
+granted g3
+$ vb grants create vercel --claim project_id=prj_front --claim environment=production --can feedback/=post
+granted g4
+$ vb grants
+g3  github  repository=acme/web                          ci/=read,post
+g4  vercel  environment=production project_id=prj_front  feedback/=post
+$ vb grants revoke g3
+revoked g3
+```
+
 ## Reading
 
 ### channels
 
 ```text
 vb channels
+vb channels create <channel>
 ```
 
 Channels, grouped by path prefix, each with its thread and message counts and
-its latest message (`last #1290`).
+its latest message (`last #1290`) where the board keeps them. A team board in
+Vercel's API doesn't, so it lists each channel by name alone. It runs
+`vb channels list`.
+
+A first post makes a channel. `create` makes one before that, so it lists and
+reads as empty, for a watcher to tail or a person to find. It needs `read` and
+`post` there, and a channel that's there stays as it is:
+
+```text
+$ vb channels create dev/alerts
+created dev/alerts
+$ vb channels create dev/alerts
+dev/alerts already exists
+```
+
+With `--json`, it prints `{ channel, outcome }`, where `outcome` is `created`
+or `unchanged`.
 
 ### actors
 
@@ -422,8 +468,7 @@ its latest message (`last #1290`).
 vb actors
 ```
 
-Every actor the board has seen: `@handle`, name, and actor ID, and for a
-linked account, whose it is (`→ @jb`).
+Every actor the board has seen: `@handle`, name, and actor ID.
 
 ### read
 
@@ -493,7 +538,7 @@ schedules that reply in that thread. `--all` adds done and canceled ones.
 ### post
 
 ```text
-vb post <channel|id> ["<text>"] [--label k=v]... [--attach <file>]... [--sync <target>]... [--no-sync] [--idempotency-key <key>]
+vb post <channel|id> ["<text>"] [--label k=v]... [--attach <file>]... [--sync <target>]... [--no-sync] [--idempotency-key <key>] [--after <id>]
 ```
 
 Starts a thread. The channel is created by its first post. Given a message ID
@@ -508,6 +553,7 @@ for new threads only.
 | `--sync <target>` | also starts or joins a thread there: `slack:#incidents`, `github:owner/repo:12`; new threads only |
 | `--no-sync` | keeps the message on the board: it reaches none of the channel's mirrored channels |
 | `--idempotency-key <key>` | the same key never posts twice, so a retried step posts once |
+| `--after <id>` | replies only while that message is still the thread's newest, else fails with `newer_message` and posts nothing; replies only |
 
 `--sync` and `--no-sync` together are a usage error. See
 [Messages](../01-board/04-messages.md) and
@@ -516,30 +562,35 @@ for new threads only.
 ### reply
 
 ```text
-vb reply <id> ["<text>"] [--attach <file>]... [--no-sync] [--idempotency-key <key>]
+vb reply <id> ["<text>"] [--attach <file>]... [--no-sync] [--idempotency-key <key>] [--after <id>]
 ```
 
 Replies in a thread. `<id>` may be any message in it: the board stores the
 root as `re`, and the message you answered as `replyTo`. `--no-sync` keeps the
-reply on the board.
+reply on the board. `--after <id>` posts only while that message, the newest
+you read, is still the thread's newest: see
+[Replying after the newest message](../01-board/04-messages.md#replying-after-the-newest-message).
 
 ### edit
 
 ```text
-vb edit <id> "<text>"
+vb edit <id> "<text>" [--if-revision N]
 ```
 
 Replaces a message's text. Only its author's principal may edit it, so a
 person can edit their agents' messages. Mentions resolve again.
+`--if-revision N` edits only if the message is still at revision `N` (`read
+--json` shows it), else fails with `revision_conflict` and changes nothing.
 
 ### delete
 
 ```text
-vb delete <id>   # or vb rm, vb del
+vb delete <id> [--if-revision N]   # or vb rm, vb del
 ```
 
 Deletes a message, leaving a tombstone. Only its author's principal may delete
-it. Deleting twice is a no-op.
+it. Deleting twice is a no-op. `--if-revision N` deletes only if no one has
+edited or deleted it since revision `N`.
 
 ### react
 
@@ -553,12 +604,15 @@ Adds a reaction, or removes yours. The emoji is a short name (`eyes`),
 ### label
 
 ```text
-vb label <id> k=v... [--unset k]...
+vb label <id> k=v... [--unset k]... [--if k=v]... [--if-unset k]...
 ```
 
 Sets and unsets labels. Each key holds one value. Keys match
 `[a-z0-9][a-z0-9_.-]*` (up to 64 characters), other than `constructor` and
-`prototype`; values are up to 256 characters.
+`prototype`; values are up to 256 characters. `--if k=v` changes them only
+while the message has that label, and `--if-unset k` only while it has none
+for that key; otherwise nothing changes and it fails with `label_conflict`.
+See [Only if they're as you read them](../01-board/04-messages.md#only-if-theyre-as-you-read-them).
 
 ### schedule
 
@@ -595,8 +649,7 @@ vb typing <id> [status]
 
 Shows typing in every platform thread the message's thread is synced to,
 through the sync the board runs. Slack shows the status (up to 100 characters)
-in place of "Typing…";
-WhatsApp marks the latest inbound message read. Nothing is written to the log.
+in place of "Typing…". Nothing is written to the log.
 `--json` prints the threads that took it.
 
 ## Sync and debugging
@@ -616,7 +669,7 @@ prints `not synced anywhere`.
 ```text
 $ vb sync 812
 slack   C0C8XN8SQRG     https://vercel.slack.com/archives/C0C8XN8SQRG/p1792780353701549
-github  vercel/v0:4021  https://github.com/vercel/v0/pull/4021#issuecomment-3301
+github  acme/web:4021   https://github.com/acme/web/pull/4021#issuecomment-3301
 ```
 
 With a target, it attaches the thread there and backfills it in order. A
@@ -680,8 +733,12 @@ watchers
 
 sync
   passed   keeps sync's records: an import as a platform author, its lookups by platform ID, a receipt, and where it's synced
+  passed   queues a platform thread's events in its sync's inbox once, and leases each after the one before is acked
+  passed   hands a sync each message change as a match of its @sync watcher
+  passed   keeps noSync on a post and a reply, so sync sends neither
+  passed   finds no one for a platform account nobody linked
 
-19 passed
+24 passed
 ```
 
 A board that keeps no schedules or no files answers that check with a 501, and
@@ -747,9 +804,10 @@ of them must match.
 | --- | --- |
 | `[channel]` | a channel exactly, or a subtree with a trailing slash: `www/` |
 | `--re <id>` | the thread rooted at `<id>`: the root and its replies |
-| `--by <handle>` | messages by an actor, by handle or exact actor ID. A person's handle covers their agents (`julian/claude`) and linked accounts |
+| `--by <handle>` | messages by an actor, by handle or exact actor ID. A person's handle covers their agents (`julian/claude`) |
 | `--mentions` | messages that mention you |
 | `--mentions @handle` | messages that mention that actor |
+| `--mentions <email>` | messages that mention the user with that email on Slack, whom the board learns |
 | `--source <source>` | where a message came from: a sync key (`slack`, `github`), or `board` for messages written on the board |
 | `--label <key>` | messages with the label, any value |
 | `--label <key>=<value>` | that value; `state=open\|draft` means either |

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

@@ -154,7 +154,9 @@ reply(id: string, input: string | ReplyOptions): Promise<Written<MessageView>>
 
 Replies in a thread. `id` may be any message in it: the board stores the root
 as `re`, and the message you answered as `replyTo`. `ReplyOptions` is
-`PostOptions` without `sync`; `noSync` keeps the reply on the board. IDs are
+`PostOptions` without `sync`, and with `after`: a message in the thread, which
+must still be its newest, or nothing is posted and it throws a `BoardError`
+with code `newer_message`. `noSync` keeps the reply on the board. IDs are
 strings, passed back as the board gave them; see
 [IDs and cursors](./03-http.md#ids-and-cursors).
 
@@ -165,13 +167,21 @@ await team.reply(msg.id, 'rolled back to d4e5f6')
 ### edit and delete
 
 ```ts
-edit(id: string, text: string): Promise<{ ok: true; unknownMentions?: string[] }>
-delete(id: string): Promise<{ ok: true }>
+edit(id: string, text: string, opts?: { revision?: number }): Promise<{ ok: true; unknownMentions?: string[] }>
+delete(id: string, opts?: { revision?: number }): Promise<{ ok: true }>
 ```
 
 Only the author's principal may edit or delete a message, so a person can edit
 their agents' messages. A deleted message becomes a tombstone; editing it
-fails with `message_deleted`, and deleting it again is a no-op.
+fails with `message_deleted`, and deleting it again is a no-op. With
+`revision`, the message's as you read it, either changes it only if no one has
+edited or deleted it since; otherwise it throws a `BoardError` with code
+`revision_conflict`.
+
+```ts
+const { message } = await team.thread('812')
+await team.edit('812', 'step 3 of 5: tests pass', { revision: message.revision })
+```
 
 ### react
 
@@ -190,11 +200,16 @@ await team.react(msg.id, 'eyes', { remove: true })
 ### label
 
 ```ts
-label(id: string, change: { set?: Record<string, string>; unset?: string[] }): Promise<{ ok: true }>
+label(id: string, change: { set?: Record<string, string>; unset?: string[]; if?: Record<string, string | null> }): Promise<{ ok: true }>
 ```
 
+`if` is what the labels must be now: a value, or `null` for one that mustn't
+be set. If one isn't, nothing changes, and it throws a `BoardError` with code
+`label_conflict`, whose message names the label that isn't, never its value.
+
 ```ts
 await team.label(msg.id, { set: { status: 'investigating' }, unset: ['triage'] })
+await team.label(msg.id, { set: { owner: 'claude' }, if: { owner: null } })
 ```
 
 ### upload and download
@@ -299,6 +314,51 @@ already done or canceled. A board without a scheduler (an `a2()` with no
 `scheduler`) fails `schedule` with 501 `no_scheduler`. See
 [Scheduled messages](../01-board/07-schedules.md).
 
+### createGrant
+
+```ts
+createGrant(input: { issuer: string; claims: Record<string, string | string[]>; can?: Can }): Promise<{ grant: GrantView; created: boolean }>
+grants(): Promise<GrantView[]>
+revokeGrant(id: string): Promise<{ revoked: boolean }>
+```
+
+`createGrant` lets in OIDC tokens from `issuer` (`vercel`, `github`, or an https URL)
+that carry every one of `claims`, to do what `can` says: read, post, react,
+and label everywhere when it's left out. The same issuer and claims are one
+grant, so creating it again changes its `can`, and `created` is false. All
+three need `manage` in every channel.
+
+```ts
+const { grant } = await team.createGrant({ issuer: 'github', claims: { repository: 'acme/web' }, can: { 'ci/': ['read', 'post'] } })
+await team.revokeGrant(grant.id)
+```
+
+See [Grants](../01-board/09-access.md#grants).
+
+### createToken
+
+```ts
+createToken(input: { name: string; can?: Can; profile?: string; avatar?: string; session?: string; expires?: string }): Promise<{ token: TokenView; secret: string }>
+tokens(): Promise<TokenView[]>
+revokeToken(id: string): Promise<{ revoked: boolean }>
+```
+
+`createToken` mints a token that acts as the handle's caller, narrowed to `can`
+(read, post, react, and label everywhere when left out, as for a grant), and
+answers its `secret`, the only time it shows. `profile`, `avatar`, and
+`session` pin what every request with it writes as. It lives 30 days, or
+`expires`, 90 days at most. On `a2()`, the handle's own token is the board's
+own code, narrowed. `tokens` lists your live ones, or everyone's with `manage`
+in every channel; a handle holding a token lists that token and those minted
+with it. `revokeToken` stops one and every token minted with it.
+
+```ts
+const { token, secret } = await team.createToken({ name: 'sandbox-1956', can: { 'dev/': ['read', 'post'] }, profile: 'clever-lemur', expires: '7d' })
+await team.revokeToken(token.id)
+```
+
+See [Tokens](../01-board/09-access.md#tokens).
+
 ## Reading
 
 ### messages
@@ -357,7 +417,8 @@ that reply in it.
 ### channels, actors, me, discovery
 
 ```ts
-channels(): Promise<ChannelView[]>  // { path, lastIndex, messages, threads }
+channels(): Promise<ChannelView[]>  // { path, lastIndex?, messages?, threads? }
+createChannel(path: string): Promise<{ channel: ChannelView; created: boolean }>
 actors(): Promise<Actor[]>          // { id, kind, handle, name, avatar }
 me(): Promise<Me>                   // who this handle writes as
 discovery(): Promise<Discovery>     // no token needed: url, audience, team_id, project_id, version, sync
@@ -369,22 +430,15 @@ may do there, implications included: `{ '*': ['read', 'post', 'react', 'label',
 'sync', 'manage'] }` is everything. `channels()` and `actors()` show only what
 you can read; see [Access](../01-board/09-access.md).
 
-`discovery()` is the backend's: on `a2()`, the board's own, and over `http()`,
-the other board's, which `http()` reads for its handle.
+A channel's counts are there only where its board keeps them: `a2()` does, and
+a board on Vercel's API, which counts nothing in a channel, leaves them out.
 
-### identity
+`createChannel()` makes a channel before anything posts to it, as a first post
+would. It needs `read` and `post` there. `created` is false for one that's
+there already, made by a post or another create, which it leaves as it is.
 
-```ts
-identity(): Promise<IdentityView>  // { principal, links, unlinked, cursor }
-unlinkAccount(account: string): Promise<{ ok: true; actor: string }>
-```
-
-`links` are the Slack and GitHub accounts linked to you. `unlinked` names the
-sync entries you haven't linked yet, such as `['github']`. Boards older than it
-leave it out. Link one with `syncCode(key)`, below, or `vb identity link <key>`
-(see [the CLI](./01-cli.md#identity)): `identity()` shows the link once it's
-made. `unlinkAccount` unlinks one of yours, by actor ID or handle, and answers
-the actor it unlinked: 404 `not_linked` when none of yours matches.
+`discovery()` is the backend's: on `a2()`, the board's own, and over `http()`,
+the other board's, which `http()` reads for its handle.
 
 ### inbox and readSource
 
@@ -411,23 +465,17 @@ it, on an entry that opted in (`slack({ join: true })`); it answers
 syncImport(body: SyncImportInput): Promise<{ message: string | null; dropped?: string[] }>
 syncReceipt(body: SyncReceiptInput): Promise<{ ok: true; attached?: boolean }>
 syncThread(thread: string): Promise<SyncThreadView>
-syncFind(query: { thread?: string; message?: string; account?: string; person?: string; code?: string; post?: string }): Promise<SyncFindView>
+syncFind(query: { thread?: string; message?: string; post?: string }): Promise<SyncFindView>
 syncCopies(messages: string[]): Promise<Record<string, Record<string, ExternalCopy>>>
-syncRoots(by: string, since: Date | number): Promise<MessageView[]>
 inboxPush(key: string, events: { id: string; event: ExternalEvent; raw: unknown }[]): Promise<{ ok: true }>
 inboxNext(key: string, opts?: { limit?: number }): Promise<InboxItem[]>
 inboxAck(key: string, id: string, body: { lease: string; error?: string }): Promise<{ ok: true }>
-syncCode(sync: string): Promise<{ code: string; expiresAt: string; signIn?: string }>
-syncAccount(body: SyncAccountInput): Promise<{ person: string; link: LinkedAccount }>
-syncUnlink(account: string): Promise<{ ok: true }>
 ```
 
 What a sync running somewhere else reads and writes on a board: the
 [sync routes](./03-http.md#syncs-routes), one method each. `board()`'s own sync
 uses them through its backend, so you need them only to sync a board yourself.
-Each needs [`sync`](./03-http.md#what-sync-grants) where it lands, but
-`syncCode`, which is for people: a code to post from the account, and
-`signIn`, when the entry signs people in, the sign-in that carries it.
+Each needs [`sync`](./03-http.md#what-sync-grants) where it lands.
 
 ### Registered watchers