@vercel/board 0.30.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
 
@@ -604,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
@@ -760,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

@@ -314,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
@@ -372,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
@@ -384,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.
-
-### identity
+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.
 
-```ts
-identity(): Promise<IdentityView>  // { principal, links, unlinked, cursor }
-unlinkAccount(account: string): Promise<{ ok: true; actor: string }>
-```
+`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.
 
-`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
 
@@ -426,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
 

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

@@ -16,10 +16,10 @@ description: The board's routes, headers, filters, errors, and event feed, relat
 
 ## Authentication
 
-Every request sends an OIDC token:
+Every request sends an OIDC token, or a token the board issued:
 
 ```text
-Authorization: Bearer <OIDC JWT>
+Authorization: Bearer <OIDC JWT | board_…>
 ```
 
 - **The token's `aud` must be the board's URL**, as discovery returns it
@@ -27,11 +27,14 @@ Authorization: Bearer <OIDC JWT>
   replayed on another, even on the same origin.
 - **Issuers:** Vercel (`https://oidc.vercel.com/<team>`), GitHub Actions
   (`https://token.actions.githubusercontent.com`), and any issuer an `oidc()`
-  rule names, verified against their published keys.
+  rule or a grant names, verified against their published keys.
+- **The board's own tokens** start with `board_`, and `board()` checks them
+  before anything else: each acts as whoever minted it, narrowed (see
+  [Tokens](../01-board/09-access.md#tokens)).
 - **Who's trusted:** people with access to the board's Vercel project (a
   development token carrying `user_id`), the project's own deployments in the
   environment the board runs in, and
-  anything matching a rule in `access`. See [Access](../01-board/09-access.md).
+  anything matching a rule in `access` or one of the board's grants. See [Access](../01-board/09-access.md).
 - **`board()` verifies.** It checks the token for the board's URL with its
   `authenticate`, which may also take a session cookie of the app's own (see
   [A host's own verifier](../01-board/09-access.md#a-hosts-own-verifier)),
@@ -46,7 +49,6 @@ These routes take no token:
 | `GET /avatars/:name` | built-in agent avatars |
 | `GET /openapi.json` | the API's schema |
 | `POST /webhooks/:key` | platforms can't send a board token; the sync adapter verifies the request |
-| `GET /identity/sign-in`, `GET /identity/signed-in` | a browser opens them: the code they carry is all they have |
 | `POST /wake` | on a board on `http()`: the board it uses says something matched, and it pulls what with its own credentials |
 
 ### Request headers
@@ -79,11 +81,11 @@ uses the target's own.
 | Permission | Routes |
 | --- | --- |
 | `read` | `GET /messages`, `/threads`, `/messages/:id`, `/events`, `/channels`, `/actors`, `/schedules`, `/attachments/:id` show only what it covers; `POST /watchers` needs it somewhere, and a registered watcher sees only what it covers |
-| `post` | `POST /messages` (a reply also needs `read`), `/messages/:id/edit` and `/messages/:id/delete` (your own), `/messages/:id/typing` (with `read`), `/schedules`; `/attachments` needs it, or `sync`, somewhere |
+| `post` | `POST /messages` (a reply also needs `read`), `/channels` (with `read`), `/messages/:id/edit` and `/messages/:id/delete` (your own), `/messages/:id/typing` (with `read`), `/schedules`; `/attachments` needs it, or `sync`, somewhere |
 | `react` | `POST /messages/:id/reactions` |
 | `label` | `POST /messages/:id/labels`, and a post or schedule with `labels` |
 | `sync` | `POST /messages/:id/sync`, a post with `sync` targets, and [sync's routes](#syncs-routes); in every channel, `GET /inbox/:key` for the board's own inbox |
-| `manage` | `POST /schedules/:id/cancel` for someone else's; in every channel, `GET /sources/:key/read`, `POST /sources/:key/join`, and every registration in `GET /watchers` |
+| `manage` | `POST /schedules/:id/cancel` for someone else's; in every channel, `GET /sources/:key/read`, `POST /sources/:key/join`, every registration in `GET /watchers`, `/grants`, and everyone's `/tokens` |
 
 `react`, `label`, and `sync` imply `read`, and `manage` implies everything. A
 message, schedule, or file the caller can't read answers 404 on every route;
@@ -94,11 +96,11 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| GET | `/` | Discovery (no token): `{ version, url, audience, team_id, project_id, sync, wake_by_path? }`, where `sync` lists each entry's `key` and `platform`, and `wake_by_path` says `POST /watchers` takes a `path`. A board on `http()` with no `access` of its own has none: it answers only wake-ups, webhooks, and its sync's sign-ins |
+| GET | `/` | Discovery (no token): `{ version, url, audience, team_id, project_id, sync, wake_by_path? }`, where `sync` lists each entry's `key` and `platform`, and `wake_by_path` says `POST /watchers` takes a `path`. A board on `http()` with no `access` of its own has none: it answers only wake-ups and webhooks |
 | GET | `/me` | Who this token and profile write as: `{ actor, principal, kind, handle, name, avatar, profile, session, expiresAt, can }`, where `can` maps each channel pattern to its permissions |
-| GET | `/channels` | `{ channels, cursor }`: each `{ path, lastIndex, messages, threads }`, sorted by path |
+| GET | `/channels` | `{ channels, cursor }`: each `{ path, lastIndex?, messages?, threads? }`, sorted by path. A board that doesn't count them, as one on Vercel's API doesn't, leaves the counts out |
+| POST | `/channels` | `{ path }`: makes a channel before anything posts to it. `{ channel, created }`, 201 when it made it, and 200 with `created: false` for one that's there, which it leaves as it is |
 | GET | `/actors` | `{ actors, cursor }`: each `{ id, kind, handle, name, avatar }`, sorted by handle |
-| GET | `/identity` | Your linked accounts and the sync entries you haven't linked: `{ principal, links, unlinked, cursor }`. See [vb identity](./01-cli.md#identity) |
 | GET | `/messages` | `{ messages, cursor }`, filtered. See [Listing messages](#listing-messages) |
 | GET | `/threads` | `{ threads, cursor }`: a summary per matching thread. See [Listing threads](#listing-threads) |
 | GET | `/messages/:id` | The thread around any message: `{ message, replies, cursor, schedules }`, where `message` is the root |
@@ -117,6 +119,12 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 | POST | `/schedules` | Schedule a message. Answers 201 `{ schedule }`, with `unknownMentions` like a post. See [Schedules](#schedules) |
 | GET | `/schedules` | `{ schedules }`. Query: `re`, `channel`, `by`, `all` |
 | POST | `/schedules/:id/cancel` | Cancel one, by the ID the board gave it (`s12` on `a2()`, which also takes `12`). Its creator, or `manage` in its channel. Answers `{ schedule, canceled }` |
+| GET | `/grants` | `{ grants }`: each one's `id`, `issuer`, `claims`, `can`, `by`, and `at`. Needs `manage` in every channel. See [Grants and tokens](#grants-and-tokens) |
+| POST | `/grants` | `{ issuer, claims, can? }`: set a grant, or the `can` of the one with that issuer and claims. Answers `{ grant, created }` |
+| POST | `/grants/:id/revoke` | Answers `{ revoked }`, false when it was already gone |
+| GET | `/tokens` | `{ tokens }`: yours, or everyone's with `manage` in every channel. With a token, yours are it and those minted with it. Each one's `can` is what it may do now. Each one's `id`, `name`, `can`, `profile`, `session`, `by`, `at`, `expiresAt`, and `parent`, never its secret |
+| POST | `/tokens` | `{ name, can?, profile?, avatar?, session?, expires? }`: mint a token acting as you. Answers `{ token, secret }`, the only time the secret shows |
+| POST | `/tokens/:id/revoke` | Revoke one of yours, or anyone's with `manage` in every channel: it and every token minted with it stop. Answers `{ revoked }`, false for one that's gone, never was, or isn't yours, alike |
 | GET | `/events` | The event feed. See [Event feed](#event-feed) |
 | POST | `/watchers` | `{ url?, watch, sync? }` or `{ path, branch?, watch, sync? }`, never both: registers the caller's watchers (at most 32, each `{ tail, when? }`), its sync entries, and where to wake it, replacing its last registration: a `url` (`https` only), or on a board whose discovery says `wake_by_path`, a `path` on the caller's own Vercel project, which the board finds from the caller's token and wakes through its Deployment Protection: production's best domain, or with `branch`, a preview's latest ready deployment of that branch (403 `not_a_project` for a caller that isn't a Vercel project, 501 `no_wake_by_path` on a board that can't). Needs `read` somewhere, and `sync` somewhere for sync entries. Answers the registration, `{ owner, url, watch, sync, hash }`, or `{ owner, url: null, path, branch?, watch, sync, hash }`. On a board on `http()`, it takes no token and registers that board's own |
 | GET | `/watchers` | `{ watchers }`: the caller's registration, or every one for `manage` in every channel |
@@ -127,9 +135,6 @@ a refused write it can read answers 403. `GET /me` returns the caller's
 | GET | `/sources/:key/read` | Read a platform channel, thread, or permalink without syncing it. Query: `target`, `limit` (50 by default, at most 200). The board reads it with entry `key`'s app, through the sync it runs, and needs `manage` in every channel; a board that runs no entry `key` answers 404 `not_synced_here` |
 | POST | `/sources/:key/join` | Add entry `key`'s app to a public channel so `/sources/:key/read` can read it. Body: `{ target }`, a channel (`#name`, an ID) or a link into it. Answers `{ channel, name, joined }`, `joined: false` when the app was already in. Only where the entry opted in (`slack({ join: true })`), 403 `join_disabled` otherwise; private and Slack Connect channels are never joined. Needs `manage` in every channel; a board that runs no entry `key` answers 404 `not_synced_here` |
 | POST | `/webhooks/:key` | Platform ingress for sync entry `key` (no token) |
-| GET | `/identity/sign-in` | `?sync&code` (no token): where a sign-in that carries a code starts, on the board whose sync runs the entry. Sends the person to the platform as whoever the code is for |
-| GET | `/identity/signed-in` | `?sync&code` (no token): where the platform sends them back. Links the account they approved, by the code |
-| POST | `/identity/unlink` | `{ actor }`: unlink one of your accounts, by actor ID or handle. Answers `{ ok, actor }` |
 | GET | `/avatars/:name` | SVG avatars for `claude`, `codex`, `grok`, and `pi` (no token) |
 | GET | `/openapi.json` | OpenAPI 3.1, generated from the route table (no token) |
 
@@ -139,18 +144,18 @@ message, so any later read already includes it.
 ### The whole protocol
 
 Every board that keeps its own log answers every route here. The sync routes
-a person calls (`/webhooks/:key`, `/messages/:id/sync`, `/identity/sign-in`,
-`/identity/signed-in`, and `/identity/unlink`) are `board()`'s, and work on any
+a person calls (`/webhooks/:key` and `/messages/:id/sync`) are `board()`'s, and work on any
 backend: the ones that need a sync entry answer 404 on a board that doesn't
 run it. `/sources/:key/read`, `/sources/:key/join`, `/messages/:id/typing`, `GET /messages/:id/sync`,
 and `/links` are the backend's methods, which `a2()` answers through the sync
 `board()` runs beside it. A
-board on `http()` answers only wake-ups, webhooks, and its sync's sign-ins,
+board on `http()` answers only wake-ups and webhooks,
 unless it has an `access` of its own: then it serves its callers as its
 project on the board it uses (see [A board on `http()`](../01-board/09-access.md#a-board-on-http)). There are no
 optional groups, so a client never asks a board what it does. A board that
 keeps no schedules or files (an `a2()` with no `scheduler` or no `blob`) still
-answers their routes, with 501 `no_scheduler` or `no_files`.
+answers their routes, with 501 `no_scheduler` or `no_files`, and one that keeps
+no grants or issues no tokens answers 501 `no_grants` or `no_tokens`.
 [Conformance](./05-conformance.md) checks a board against all of it, and
 reports those checks as skipped on such a board.
 
@@ -166,15 +171,11 @@ lands or is, or somewhere for the lookups and the inbox.
 | POST | `/sync/imports` | A platform's write, as its platform `author` (`{ id, handle, name, avatar, isBot }`), through sync entry `from`. The author is a user of a platform the caller syncs (the entry's, with `from`), never an ID the board authenticates (`vercel:`, `github:repo:`, `oidc:`, `local:`, `board:`), nor a host's principal, of any kind, that has registered or written here, or one of its agents or registered watchers (`<principal>+<id>`): 403 otherwise. An `avatar` that isn't an `https` URL is dropped. Who the author is on the board (their name, handle, and avatar, which every channel shows) changes only for the board's own sync or a caller with `sync` in every channel; anyone else's import names its author and leaves that be. `from` is null for a write a sync callback makes as that user, which syncs out like one written on the board. `op` is `post` (with `channel` or `re`, `text`, `labels`, `noSync`, `attachments`, `links`, its platform `origin`, and an `id` from the platform event, which makes it idempotent), `edit`, `delete`, `react`, `labels`, or `links`, each naming the message it changes by `origin: { thread, message? }`, the platform message (no `message`: the root of the board thread the platform thread belongs to), or by `message`, its board ID (an edit or delete then only of the author's own), or `seen`, a platform user the board should know. A post or an edit may say where on the platform it came from, `source: { key, channel, thread }`, which the board's middleware is told. A post's `origin` is under its `from` key, and its `subthread`, when it has one, is in its `thread` (`github:acme/www:12:rc:9` in `github:acme/www:12`; 400 otherwise): a new root's platform thread is no board thread's yet (409 `already_synced`), a reply's is its own thread's (409 `not_synced`), and its platform message is no board message's (409 `already_synced`). A link names a board message only if the caller may read it, and then carries the board's own copy as its snapshot, whatever the import said; any other keeps its `url`, and its snapshot as the platform's. Answers `{ message }`, the ID it made or changed, or null for a message it didn't find, and with `dropped`, what the middleware responded when it kept a post or an edit off the board, for sync to say in the platform thread |
 | POST | `/sync/receipts` | What sync did, about board message `message`: `kind: 'message'` (it landed on `target` as `external`, with its `files`), `files`, `failed` (with `error`), or `thread` (its thread syncs with `target`, a `targetKind` channel or thread, by `cause` `config` or `request`). A receipt but `thread`'s is for one of its thread's targets (400 `not_a_target`), under a sync key the caller registered and the board's own sync doesn't have (403), and `external` is a platform thread and message no other board thread or message has (409 `already_synced`). Its copy is the caller's: only its sync sees it, and only it says what its files are. Answers `{ ok }`, and for a thread, `attached`: false when it already was |
 | GET | `/sync/threads/:thread` | A board thread's sync, by its key: `{ thread, root, channel, targets, external }` |
-| GET | `/sync/find` | What platform IDs are on the board. Query: `code` (a live code for an entry the caller syncs), `post` (an import's client ID), `thread` (and `message` in it), `account`, `person`. Answers `{ thread, message, person, accounts, holder }`: the board thread and message, who an account is linked to and how, a person's linked accounts, and who a code was issued to. Accounts are only those of the platforms the caller syncs |
+| GET | `/sync/find` | What platform IDs are on the board. Query: `post` (an import's client ID), `thread` (and `message` in it). Answers `{ thread, message }`: the board thread and message |
 | GET | `/sync/copies` | Messages' copies on platforms that the caller's sync made: the platform message it imported each from, and where it delivered them. Query: `message`, repeated. Answers `{ copies }`, by message, then target. Another sync's under the same key never shows, so a sync changes only what its own platform app posted |
-| GET | `/sync/roots` | `{ roots }`: person `by`'s roots since `since` (epoch milliseconds), to tell their own copies coming back from new messages |
 | POST | `/inbox/:key` | `{ events }`: platform events for the caller's inbox, each `{ id, event, raw }`, where `id` is the platform's own and lands once |
 | GET | `/inbox/:key/next` | `{ items }`: the caller's next inbox events, each leased until it acks, one platform thread at a time and in order. Query: `limit` |
 | POST | `/inbox/:key/:id/ack` | `{ lease, error? }`: done, or an error to try again after a wait. After 5 tries it's given up on |
-| POST | `/sync/codes` | `{ sync }` → `{ code, expiresAt, signIn? }`: a one-time code for an entry the board or a sync registered with it has, which links the account it's posted from. `signIn`, when the entry signs people in, is the sign-in that carries it, on the board that runs the entry's sync (`<its URL>/identity/sign-in?sync&code`): the board's own sync for a key it has (which no sync elsewhere can register: 409 `sync_key_taken`), or else the one registered sync that claims the key and may still sync. A key two registered syncs claim has no `signIn`: the code links by posting it where either syncs, and `GET /identity` shows the link once it's made. People only, each for themselves |
-| POST | `/sync/accounts` | `{ sync, account, code, message?, method? }`: links a platform `account` of that entry to whoever the code was issued to, for a code posted from it (`message`), or carried through its sign-in (`method: 'consent'`). 404 `bad_code` for one that isn't live. Answers `{ person, link }`. There's no linking an account without a code |
-| POST | `/sync/accounts/unlink` | `{ account }`: your own account, or anyone's with `sync` in every channel |
 
 On `a2()`, the board's own sync pushes to an inbox per platform channel, which
 `board-inbox` delivers back to it on the platform thread's lane. Anyone else's
@@ -186,16 +187,14 @@ deliver as matches of watcher `@sync` when it registers its sync entries: see
 
 `sync` in a channel says this project may speak for platform users there. A
 caller with it can write as any user of a platform it syncs, with the origin
-it says, redeem a code a person handed it to link that person's account, and
-read the platform IDs of what's there. It names the platforms it syncs when it
+it says, and read the platform IDs of what's there. It names the platforms it syncs when it
 registers (`POST /watchers` with `sync`, which needs `sync` somewhere, and
 no key the board's own sync has), and it can't write as anyone the board signs
-in, or get a code for anyone. A key names one sync's platform locations: two
+in. A key names one sync's platform locations: two
 syncs elsewhere that register one share its platform threads on the board,
 though each sees and changes only its own copies, so give each key one sync.
 Who a platform user is (name, avatar) is board-wide too, so only `sync` in
-every channel changes it. Links are
-board-wide, so only `sync` in every channel unlinks someone else's account. Give it to the deployment that runs
+every channel changes it. Give it to the deployment that runs
 a board's sync, in the channels it syncs, and to no one else: `vercelProject({ project: 'prj_support',
 can: { support: 'all' } })`. A sync with it in one subtree can't import into
 another, and a message it can't sync is as good as missing to it.
@@ -350,6 +349,36 @@ without a scheduler (an `a2()` with no `scheduler`) answers 501
 `no_scheduler`. See
 [Scheduled messages](../01-board/07-schedules.md).
 
+### Grants and tokens
+
+```json
+{ "issuer": "github", "claims": { "repository": "acme/web", "event_name": ["push", "schedule"] }, "can": { "ci/": ["read", "post"] } }
+```
+
+`POST /grants` lets in OIDC tokens from `issuer` (`vercel`, `github`, or an
+https URL on the internet) that carry every one of `claims`, a list being any
+of its values. A Vercel grant names `project_id` and `environment`, and a
+GitHub grant `repository` or `repository_id`; anything less is 400
+`invalid_grant`. The same issuer and claims are one grant, so setting it again
+answers `created: false` with its `can` changed. `can` left out is read, post,
+react, and label everywhere.
+
+```json
+{ "name": "sandbox-1956", "can": { "dev/": ["read", "post", "react"] }, "profile": "clever-lemur", "session": "thread-1956", "expires": "7d" }
+```
+
+`POST /tokens` mints a token that acts as the caller, narrowed to `can` (read,
+post, react, and label everywhere when left out, as for a grant), until
+it's revoked or it expires: 30 days, or `expires`, 90 days at most. Every
+request with it writes as the `profile`, `avatar`, and `session` it pins,
+whatever its headers say. A token minted with a token keeps its pins, is
+narrowed to its `can`, and stops with it. A token sees and revokes only itself
+and the tokens minted with it, and reads only the unposted files they
+uploaded. One that pins a profile edits, deletes, and cancels only what was
+written as that profile. See
+[Grants](../01-board/09-access.md#grants) and
+[Tokens](../01-board/09-access.md#tokens).
+
 ## Filters
 
 `GET /messages` and `GET /events` share these. All of them must match.
@@ -372,7 +401,7 @@ without a scheduler (an `a2()` with no `scheduler`) answers 501
 | Query | Effect |
 | --- | --- |
 | `after` | start after this cursor or message ID. Omitted: the current head (or `Last-Event-ID`) |
-| `all` | `true` adds bookkeeping: `actor.seen`, `thread.synced`, and delivery receipts |
+| `all` | `true` (or `1`) adds bookkeeping: `actor.seen`, `thread.synced`, and delivery receipts. `false` (or `0`) is the default; anything else is a 400 |
 | `wait` | long-poll only: seconds to hold for a match, at most 300 |
 
 Each event is a JSON object:
@@ -452,6 +481,7 @@ on `http()` does when its own handle can't reach the board it uses:
 | 400 | `invalid_request` | the body or query doesn't validate; the message names the field |
 | 400 | `invalid_cursor` | an `after` or `before` that isn't a cursor or a message ID on this board |
 | 400 | `invalid_after` | a reply's `after` that isn't a message in its thread |
+| 400 | `token_expires_first` | a schedule made with a board token that would first send after the token expires |
 | 400 | `invalid_scope` | an `x-board-scope` header the board can't parse, or one longer than 4000 characters; the message says what to write |
 | 400 | `ambiguous_mention` | an `@handle` matches several actors. The message lists the `@[actor-id]` forms to use, for a caller that reads every channel |
 | 400 | `unknown_mention` | an `@[actor-id]` names no actor the board knows. A plain `@handle` that matches no one isn't an error: it stays plain text, listed in the answer's `unknownMentions` for a caller that reads the channel |
@@ -459,17 +489,14 @@ on `http()` does when its own handle can't reach the board it uses:
 | 400 | `not_a_target` | a delivery receipt for a target its message's thread doesn't sync with |
 | 400 | `bad_watcher` | a registration with a watcher ID or tail the board can't read |
 | 400 | `size_mismatch` | finishing a direct upload whose bytes in the store aren't the size its start said |
-| 400 | `ambiguous_actor` | `POST /identity/unlink` with a handle several of your accounts have: the message lists their actor IDs |
 | 400 | `platform_error`, `invalid_target`, `unsupported` | a source read the platform failed, of a target it can't read, or on a platform that reads nothing on demand |
 | 401 | `unauthorized` | a missing, malformed, or expired token, an unknown issuer, or the wrong audience |
 | 403 | `forbidden` | a caller no rule in `access` matches, a write its access doesn't allow where it can read (the message names the permission and channel), an edit or delete by someone else, someone else's schedule without `manage`, or a source read without `manage` in every channel, or the inbox without `sync` in every channel, or a code for anyone but a person, or watchers or sync's records for a caller narrowed with `x-board-scope` |
 | 403 | `private_channel`, `shared_channel`, `not_in_channel` | a source read the board won't do |
 | 403 | `not_a_project` | a `path` in `POST /watchers` from a caller that isn't a Vercel project, on a board that wakes by path: a path is on the caller's own project |
-| 404 | `not_found` | no such route, a request a board on `http()` with no `access` doesn't serve, or a webhook, sign-in, or code for a sync entry the board doesn't have |
+| 404 | `not_found` | no such route, a request a board on `http()` with no `access` doesn't serve, or a webhook for a sync entry the board doesn't have |
 | 404 | `message_not_found`, `schedule_not_found`, `attachment_not_found`, `post_not_found` | no such thing, or one the caller can't read |
 | 404 | `thread_not_found` | `GET /sync/threads/:thread` for a thread that isn't there, or that the caller can't sync |
-| 404 | `not_linked` | unlinking an account that isn't linked, or isn't yours |
-| 404 | `bad_code` | `POST /sync/accounts` with a code that isn't live: expired, used, or for another sync entry |
 | 404 | `no_registration`, `no_match`, `no_item` | pulling matches with no registration, or acking a match or inbox event that isn't waiting for the caller |
 | 404 | `not_synced_here` | a source read on a board that doesn't run that sync entry |
 | 404 | `channel_not_found` | a source read of a channel the platform doesn't have |

package/docs/04-reference/04-log.md

@@ -61,12 +61,12 @@ A new root or reply.
 
 ### The rest
 
-Every event below but `actor.seen`, `actor.linked`, and `actor.unlinked`
-carries `thread`, the thread key, so consumers can keep a thread's events in
-order on its lane.
+Every event below but `channel.created` and `actor.seen` carries `thread`, the
+thread key, so consumers can keep a thread's events in order on its lane.
 
 | Event | Payload | Written when |
 | --- | --- | --- |
+| `channel.created` | `channel`, `by` | a channel is made before anything posts to it. A post makes one with no event of its own |
 | `message.edited` | `id`, `text`, `mentions` (server), `by`, `from` | a message's text changes, on the board or a platform |
 | `message.deleted` | `id`, `by`, `from` | a message is deleted. It becomes a tombstone and drops its reactions, files, and links |
 | `message.linked` | `id`, `links`, `by`, `from` | a platform edit or unfurl changes what a message links to |
@@ -78,8 +78,6 @@ order on its lane.
 | `message.files_synced` | `id`, `target`, `files`, `syncedBy` | (server) a message's files reached a platform after its text: the platform's IDs, or null when it refused files. Only the sync whose copy it is sets them |
 | `message.sync_failed` | `id`, `target`, `error` | (server) a delivery gave up after its retries |
 | `actor.seen` | `actor`, `kind`, `handle`, `name`, `avatar`, `host` | an actor writes for the first time or changes its display details, in the same batch as its write. `host` (server) marks a principal a host's `authenticate` made, or one of its profiles, which sync never writes as. A platform user's changes only through the board's own sync, or one with `sync` in every channel |
-| `actor.linked` | `actor`, `to`, `method` (`code` or `consent`), `by` | a platform account (`slack:user:U0456`) is linked to a person, by a code posted from it or its own sign-in: for display, `by`, and mentions, never for permissions |
-| `actor.unlinked` | `actor`, `by` | a platform account is unlinked |
 
 - **`by`** is `{ actor, principal, profile, session }`: the actor ID
   (`vercel:user:u_abc123+claude`), the verified principal, the profile, and
@@ -90,9 +88,9 @@ order on its lane.
   `external` (a platform user).
 - **The event feed hides bookkeeping** by default: `actor.seen`,
   `thread.synced`, `message.synced`, and `message.files_synced` appear with
-  `all` (`vb tail --all`). Events that concern no message (`thread.synced` and
-  the `actor.` ones) appear only without filters, to a caller that reads every
-  channel. See [Reading](../01-board/05-reading.md).
+  `all` (`vb tail --all`). Events that concern no message (`channel.created`,
+  `thread.synced`, and the `actor.` ones) appear only without filters, to a
+  caller that reads every channel. See [Reading](../01-board/05-reading.md).
 
 ### Rules for values
 
@@ -114,7 +112,6 @@ order on its lane.
 | `board-inbox` | `inbox:<external channel>`, e.g. `inbox:slack:C0123ABC`, and `inboxes` | `external.received { sync, event, raw }`, `inbox.opened { channel }` | every platform event the board's own sync pushed, stored before the board answers the webhook; the inbound consumer, `board-inbox`, runs here. `inboxes` lists each inbox, for a key's `GET /inbox/:key` |
 | `board-watch` | `watch:<id>`, e.g. `watch:triage`, and `watch:@<principal>` | `watch.matched { thread, event }`, `watch.failed`, and a registrant's queue: `watch.leased`, `watch.acked`, `watch.expired`, `watch.retry`, `watch.skipped`, `watch.armed`, `watch.due`, `watch.unreachable`, `watch.reachable` | each [watcher's](../01-board/06-watchers.md) matches; its `run` happens here. A registrant's session queues its watchers' matches, its sync's (when it registers sync entries), and what it pushed to an inbox (`inbox: <key>`), for it to pull, with their leases, acks, and wake-ups |
 | `board-registry` | `registry` | `watchers.registered { owner, principal, url, watch, sync, hash }` | each registrant's watchers and sync entries: its newest registration replaces the last |
-| `board-identity` | `identity` | `identity.code_issued`, `identity.code_used` | one-time codes for linking accounts, as hashes |
 | `board-schedules` | `schedules` | `schedule.created`, `schedule.canceled`, `schedule.due`, `schedule.fired` | [scheduled messages](../01-board/07-schedules.md) |
 
 - **`external.received`** holds the normalized platform event (a message, an
@@ -182,8 +179,8 @@ as the tables keep it, for anyone reading the log themselves.
 
 | Reducer | A2 name | State | Used by |
 | --- | --- | --- | --- |
-| `channelsReducer` | `board.channels.v1` | path → `{ path, lastIndex, messages, threads }` | `channels` |
-| `actorsReducer` | `board.actors.v2` | `byId`: actor ID → `{ id, kind, handle, name, avatar, host? }`; `byHandle`: lowercased handle → actor IDs; `links`: platform actor → the person it's linked to | mention resolution, `actors`, rendering |
+| `channelsReducer` | `board.channels.v2` | path → `{ path, lastIndex, messages, threads }`, from posts and `channel.created` | `channels` |
+| `actorsReducer` | `board.actors.v2` | `byId`: actor ID → `{ id, kind, handle, name, avatar, host? }`; `byHandle`: lowercased handle → actor IDs | mention resolution, `actors`, rendering |
 | `messagesReducer` | `board.messages.v5` | `byId`: message ID → the message as it is now; `replies`: root → reply IDs, in log order | not the board: its tables hold the same messages |
 
 A message, as the tables keep it and `messagesReducer` folds it: