@abloatai/ablo 0.11.1 → 0.12.0

package/dist/types/streams.d.ts

@@ -57,28 +57,6 @@ export interface AgentDelta {
     causedByTaskId?: string | null;
     createdAt: string;
 }
-/**
- * A reference to whoever's authority bounds a joined participant.
- * The spawned participant can never see or do more than this principal.
- * Enforced server-side: the spawned agent gets its own restricted
- * (`rk_`) key whose scope is a subset of the parent's.
- *
- *   • `SessionRef`     — human is joining an agent (chat assistant flow)
- *   • `AgentRef`       — agent spawning a sub-agent (attenuation chain)
- *   • omitted          — the API key on the Ablo client is the ceiling
- */
-export type Principal = SessionRef | AgentRef;
-export interface SessionRef {
-    readonly kind: 'session';
-    readonly id: string;
-    readonly userId: string;
-    readonly organizationId: string;
-}
-export interface AgentRef {
-    readonly kind: 'agent';
-    readonly id: string;
-    readonly capabilityToken: string;
-}
 /**
  * Flat snapshot view returned from `participant.snapshot(...)`.
  *
@@ -382,7 +360,7 @@ export interface ClaimStream {
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
      * `status: 'queued'` claims behind the current holder, each with its
-     * `action`, `heldBy`, and `position`. Synced from the server's per-entity
+     * `reason`, `heldBy`, and `position`. Synced from the server's per-entity
      * `claim_queue` frame; empty when no one's waiting. Pair with
      * `subscribe(...)` for change notifications.
      */
@@ -479,10 +457,12 @@ export interface ClaimDeclaration {
     /** Human-readable reason — "rewriting title" / "restyling chart". */
     readonly reason: string;
     /**
-     * Expiry — auto-revoke if the participant doesn't finish in time.
-     * Number = seconds (back-compat); string = duration (`'3m'`).
+     * Seconds remaining until the server auto-expires this claim. An OUTPUT
+     * field carrying a concrete countdown, so it's a plain `number` — distinct
+     * from the input `ttl: Duration` (`'3m'`) you pass when announcing. Computed
+     * from `expiresAt - now`.
      */
-    readonly ttlSeconds?: Duration;
+    readonly ttlSeconds?: number;
 }
 /**
  * Handle returned from `announce(...)` / `analyzing(...)` / etc.
@@ -529,7 +509,13 @@ export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposabl
         readonly range?: TargetRange;
         readonly meta?: Record<string, unknown>;
     };
-    readonly action: string;
+    /**
+     * The human-readable phase this claim represents — `'editing'`, `'writing'`,
+     * `'forecasting'`. The SAME word on every claim surface (inputs and outputs);
+     * distinct from the CRUD operation (`CommitOperationInput.action`). Defaults
+     * to `'editing'`. Serialized on the wire as `action`.
+     */
+    readonly reason: string;
     readonly description?: string;
     /** Row snapshot — populated by `ablo.<model>.claim`; absent on low-level leases. */
     readonly data?: T;
@@ -587,8 +573,10 @@ export interface Claim {
     readonly status: ClaimStatus;
     /** What is being coordinated. */
     readonly target: EntityRef;
-    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. */
-    readonly action: string;
+    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
+     *  field on every claim surface; distinct from the CRUD operation. Serialized
+     *  on the wire as `action`. */
+    readonly reason: string;
     /** Peer-visible explanation of the work being performed. */
     readonly description?: string;
     /** Participant holding it. */

package/dist/utils/mobx-setup.js

@@ -145,6 +145,7 @@ export function M1(target, propertyMetadata, referenceMetadata) {
         'propertyChanged',
         'markAsPersisted',
         'clearChanges',
+        'consumeModifiedFields',
         'updateFromData',
         'applyChanges',
     ];

package/docs/api-keys.md

@@ -12,6 +12,55 @@ The key identifies the Ablo account. Application code does not pass an organizat
 
 "Trusted" means the runtime can hold a secret: a backend or other server-side environment a browser can't read. Browser and app clients use the same `@abloatai/ablo` import but authenticate differently — they never carry a secret key.
 
+## Which credential to use
+
+There's **one field — `apiKey`** — and what you pass depends on **where the code runs**.
+Pick your row:
+
+| Where your code runs | What to pass | Example |
+|---|---|---|
+| **Server / worker / CLI** (can hold a secret) | your secret `sk_` — it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
+| **Browser — read-only** | a publishable `pk_` (safe to ship, like a Stripe `pk_`) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
+| **Browser — writing as the signed-in user** | a function that fetches a short-lived per-user token from your own backend | `Ablo({ schema, apiKey: () => fetch('/api/ablo-session').then((r) => r.text()) })` |
+
+That's the whole story: one knob, filled by audience.
+
+**Coming from Stripe? It's the same key model, same prefixes:**
+
+| Stripe | Ablo | Where it goes |
+|---|---|---|
+| publishable `pk_` (client-safe) | `pk_` | browser — read-only |
+| secret `sk_` (server, full) | `sk_` | server — full authority |
+| restricted `rk_` (granular) | `rk_` | scoped agent sessions (`sessions.create({ agent, can })`) |
+| ephemeral key (client, customer-scoped) | `ek_` | per-user browser sessions (`sessions.create({ user })`) |
+
+Mode lives in the prefix too — `sk_test_` / `sk_live_` — exactly like Stripe. The
+`apiKey` resolver fetching an `ek_` is Ablo's ephemeral-key flow: server mints, client holds.
+
+**Why a function for browser writes?** Anything you ship to a browser must be public, and a
+public `pk_` is **read-only** — it can't carry one specific user's write authority. So when
+the browser writes *as the logged-in user*, your backend (which holds the secret `sk_` and
+knows who's signed in) mints a short-lived per-user token with `sessions.create({ user })`,
+and the browser's `apiKey` function fetches it. You don't manage refresh — the SDK calls the
+function once before connecting and then keeps the token fresh (re-mint before expiry, and on
+tab-focus / network-online / device-wake). This is the Stripe ephemeral-key / Supabase
+session model. For a read-only app you don't need any of this — just the `pk_` above.
+
+Server-side, because `apiKey` defaults to `process.env.ABLO_API_KEY`, most backend and agent
+code passes nothing. The secret `sk_` (and `databaseUrl`) are **server-only** — never in a
+browser bundle. There is no `getToken`, `authEndpoint`, or `as` option — `apiKey` (a string,
+or a function for the browser-write case) is the single credential knob.
+
+### Minting per-user / agent tokens (server-side, with your `sk_`)
+
+| Mint | Call | Result |
+|---|---|---|
+| Human end-user session | `await server.sessions.create({ user: { id } })` | `ek_` (full user authority) |
+| Scoped delegated agent | `await server.sessions.create({ agent: { id }, can: { Task: ['update'] } })` | `rk_` (scoped to `can`) |
+| Connect Ablo to your own Postgres | `Ablo({ schema, apiKey, databaseUrl })` (server-only) | dedicated tenant |
+
+The principal kind comes from *which* shape you pass — `{ user }` → `user`, `{ agent, can }` → `agent`.
+
 ## Server-Side API Keys
 
 Use API keys from trusted (server-side) runtimes:

package/docs/api.md

@@ -167,8 +167,9 @@ side: it takes the claim and returns a `ClaimHandle`. Claims don't lock — if s
 already holds the row, `claim` waits for them to finish, re-reads the fresh row,
 then hands it to you, so you always proceed from current state. Default reads
 return the row even while someone is mid-edit; if a server read should not
-return a row while it's claimed, pass `ifClaimed: 'wait'` to wait for the claim
-to clear, or `ifClaimed: 'fail'` to error out instead.
+return a row while it's claimed, pass `ifClaimed: 'fail'` to error out instead.
+Reads never block on a claim — to wait for a row to free up, `claim({ id })` it
+(the claim queues fairly behind the holder).
 
 ```ts
 const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });

package/docs/client-behavior.md

@@ -32,6 +32,7 @@ Common options:
 | `databaseUrl` | Optional, server-only. Registers your Postgres directly (the connection-string path). Pass it explicitly — it is **not** auto-read from the environment. Omit it for a signed Data Source endpoint or the hosted sandbox. The SDK throws if it sees this in a browser. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
+| `transport` | `'websocket'` (default) is the live, stateful client — a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (`get`/`getAll`, `onChange`, `watch`) are compile errors rather than runtime gaps. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |

package/docs/coordination.md

@@ -1,9 +1,10 @@
 # Coordination Reference
 
 Coordinate long-running work on a row so humans and agents don't clobber each
-other. Most writes need none of this — `ablo.<model>.update({ id, data })` is optimistic
-and the server rejects it if the row moved. Reach for `claim` only when you'll
-**hold a row across a slow gap** (read → LLM call → write).
+other. Most writes need none of this — a plain `ablo.<model>.update({ id, data })`
+is **last-write-wins** by default. For lost-update detection, take a claim or pass
+`readAt` / `onStale` yourself. Reach for `claim` only when you'll **hold a row
+across a slow gap** (read → LLM call → write).
 
 Claims don't lock. If another writer holds the row, `claim` waits for them,
 re-reads the fresh row, then hands it to you — so two writers serialize instead
@@ -36,10 +37,12 @@ make:
 **The one decision: do you hold the row across a slow gap (read → LLM call →
 write)?**
 
-- **No** (the common case — a single quick `update`): do nothing. `ablo.<model>.update`
-  is optimistically guarded by stale-context already; it rejects with
-  `AbloStaleContextError` if the row moved under you. This is the default and
-  needs no ceremony.
+- **No** (the common case — a single quick `update`): a plain `ablo.<model>.update`
+  is **last-write-wins** — it carries no `readAt`, so the server skips the stale
+  check and the write simply lands. That's fine for most fields. If you need
+  lost-update detection on a no-claim write, pass `readAt` + `onStale: 'reject'`
+  yourself and it rejects with `AbloStaleContextError` when the row moved under
+  you.
 - **Yes** (you'll reason for seconds while holding the row): `claim` it. The claim
   excludes other participants for the duration, queues contenders fairly, and —
   see below — your own writes under it stay stale-guarded too.
@@ -48,12 +51,13 @@ write)?**
 non-holder writing to a claimed row is rejected (`AbloClaimedError`) regardless of
 `readAt`. If you do hold it, your own writes are still stale-checked — a row that
 moved between your snapshot and your write still rejects with
-`AbloStaleContextError`. With no claim held, the stale check is the only
-protection, and it's automatic, which is why the no-claim path is safe by default.
-Presence (`claim.state`) never decides anything — read it to render, act on the
-errors. The two checks are independent: one rejects writes from people who don't
-hold the claim, the other rejects writes based on a stale snapshot, and the SDK
-adds the stale-check for you when you write under a claim, so you don't pass
+`AbloStaleContextError`. With no claim held and no `readAt`, there is **no**
+stale protection — the plain write is last-write-wins; opt into lost-update
+detection by passing `readAt` + `onStale` yourself. Presence (`claim.state`)
+never decides anything — read it to render, act on the errors. The two checks are
+independent: one rejects writes from people who don't hold the claim, the other
+rejects writes based on a stale snapshot, and the SDK adds the stale-check for you
+when you write under a claim **you took on this client**, so there you don't pass
 anything extra.
 
 ---
@@ -92,6 +96,17 @@ a model row. It's what `claim.state()` returns and what observers render.
 
 ## Methods
 
+One word — "claim" — names four distinct things; keep them separate as you read:
+
+- **the lease (claim handle)** — the *object* returned by `ablo.<model>.claim({ id })`
+  (`ClaimHandle`, an `AsyncDisposable` with `.data` and `.release()`).
+- **acquiring a claim/lease** — the *verb* `ablo.<model>.claim({ id })`, the call
+  that takes the lease.
+- **`claim.state` / `claim.queue`** — the *inspection namespace* hanging off the
+  model, for reading who holds the row and who's lined up.
+- **the write's `claim` param** — `update({ id, data, claim })`, where you pass a
+  lease the proxy didn't take itself.
+
 Each method below follows one fixed shape: **signature · what it does ·
 parameters · returns · example**.
 
@@ -149,15 +164,19 @@ held. Server/model reads can choose a claimed policy:
 ```ts
 await ablo.weatherReports.retrieve({
   id: 'report_stockholm',
-  ifClaimed: 'wait',
-  claimedTimeout: 30_000,
+  ifClaimed: 'fail',
 });
 ```
 
-- `ifClaimed: 'return'` reads now and includes active work metadata.
-- `ifClaimed: 'wait'` waits for the active claim to clear before reading.
+- `ifClaimed: 'return'` (the default) reads now and includes active work metadata.
 - `ifClaimed: 'fail'` throws `AbloClaimedError` if the row is claimed.
 
+Reads never block on a claim — there is no `ifClaimed: 'wait'`. Waiting for a row
+to free up is a **claim-side** concern: take `ablo.<model>.claim({ id })` (it
+queues fairly behind the current holder and re-reads the fresh row once it's
+yours). Use `ifClaimed: 'fail'` when a read should simply refuse to proceed
+against a row someone else is mid-editing.
+
 ### `claim.state`
 
 ```ts
@@ -272,19 +291,54 @@ try {
 }
 ```
 
+### `watch` — presence for a set of rows
+
+Reading or claiming a row auto-enrolls you in its sync group, which is enough for
+`claim.state`/`claim.queue` to observe co-participants. When you want to *hold*
+presence on a known set of rows — a deck's slides, a board's cards — and react to
+who joins or leaves, use `watch`:
+
+```ts
+await using room = await ablo.slides.watch(slideIds, { ttl: '5m' });
+room.peers; // who else is here, live
+```
+
+`watch(ids, { ttl? })` opens a model-scoped presence/claim subscription and returns
+a participant handle (`.peers`, the scoped claim stream, `.leave()` / `await using`
+disposal). It is the model-scoped successor to the old top-level
+`ablo.participants.join({ scope })`. **WebSocket only** — presence needs a live
+socket, so `watch` is absent on the HTTP client (`Ablo({ transport: 'http' })`) and
+throws on any non-ws construction.
+
 ### Writing under a claim
 
 There is no separate "write" method on a claim — use the normal
-`ablo.<model>.update({ id, data })`. While you hold a claim on `id`, that `update` is
-automatically stale-guarded against the snapshot the claim took (`readAt` =
-snapshot watermark, `onStale: 'reject'`) and attributed to the claim's lease, so
-it rejects with [`AbloStaleContextError`](#errors) if the row changed under you.
+`ablo.<model>.update({ id, data })`. The auto-guarding holds **only when this same
+client took the claim** via `ablo.<model>.claim({ id })` (the proxy remembers the
+lease in-process): that `update` is then stale-guarded against the snapshot the
+claim took (`readAt` = snapshot watermark, `onStale: 'reject'`) and attributed to
+the claim's lease, so it rejects with [`AbloStaleContextError`](#errors) if the
+row changed under you.
 
 ```ts
 await using claim = await ablo.weatherReports.claim({ id });
 await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // guarded by the claim
 ```
 
+A claim handle minted by **another client** (or returned over HTTP) is not known
+to this proxy, so a plain `update` won't pick it up. Pass it explicitly:
+
+```ts
+await ablo.weatherReports.update({ id, data: { status: 'ready' }, claim: handle });
+```
+
+**Self-stale on a second write.** The claim's watermark is fixed at claim time
+and is **not** re-baselined as you write. So a *second* `update` under one held
+claim is stale-checked against the snapshot the claim took — which your *first*
+write already moved past — and rejects with `AbloStaleContextError` against your
+own earlier write. Re-read (and re-claim) between writes if you need to write the
+same row more than once under one claim.
+
 Claims are **enforced server-side**: if you `update`/`delete` a row that *another*
 participant holds, the commit is rejected with [`AbloClaimedError`](#errors) (`code:
 'entity_claimed'`). To proceed, `claim` the row yourself — the claim queues

package/docs/examples/existing-python-backend.md

@@ -57,8 +57,9 @@ export const ablo = Ablo({
 ```
 
 Mount the React provider near the app root. Build the browser client first —
-with an `authEndpoint` so it mints a short-lived session token instead of
-carrying the secret key — then pass it to the provider via `client`.
+with an `apiKey` resolver (an async `() => Promise<string | null>`) that fetches
+the short-lived session token your backend minted, instead of carrying the
+secret key — then pass it to the provider via `client`.
 
 ```tsx
 // web/app/providers.tsx
@@ -68,9 +69,12 @@ import Ablo from '@abloatai/ablo';
 import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
-// Browser client: no secret key — `authEndpoint` mints the session token
-// server-side (see the session route below).
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+// Browser client: no secret key — the `apiKey` resolver fetches the session
+// token your server route mints (see the session route below).
+const ablo = Ablo({
+  schema,
+  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+});
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider client={ablo}>{children}</AbloProvider>;

package/docs/examples/scoped-agent.md

@@ -81,7 +81,7 @@ import { schema } from './schema';
 
 const ablo = Ablo({
   schema,
-  getToken: async () => mintDeckAgentSession(deckId, agentId),
+  apiKey: async () => mintDeckAgentSession(deckId, agentId),
 });
 
 // The agent run is mounted on behalf of its triggering user.

package/docs/guarantees.md

@@ -82,9 +82,10 @@ Claims are live coordination signals. They are not database locks.
 already holds the row, the claim waits for them to finish, then re-reads the row
 before handing it back, so you proceed from fresh state. Reads stay open while a
 claim is held — `ablo.<model>.claim.state({ id })` returns the current claim state
-(or `null`) without ever blocking. A server read can pass `ifClaimed: 'wait'` to
-wait for the claim to clear, or `ifClaimed: 'fail'` to error out, when it should
-not return a row while someone else is mid-edit.
+(or `null`) without ever blocking. A server read can pass `ifClaimed: 'fail'` to
+error out, when it should not return a row while someone else is mid-edit. Reads
+never block on a claim — to wait for a row to free up, `claim({ id })` it (the
+claim queues fairly behind the holder).
 
 A claim does not reject or block other writers; it announces work so peers
 serialize behind it rather than racing. While you hold a claim, the matching

package/docs/identity.md

@@ -36,8 +36,8 @@ runnable place, so the concepts below have code to attach to.
 ## Declare it, end to end
 
 The entire declaration surface is: `identityRoles` (who may see what), and on
-each model `scope` / `parent` / `grants` (which group a row fans out on), plus an
-optional `scope` setting on the client (narrowing). Read the three blocks first —
+each model `scope` / `parent` / `grants` (which group a row fans out on), plus
+optional `syncGroups` at session-mint time (narrowing). Read the three blocks first —
 a human gets their `org` / `team` scope, an agent gets one `deck` — then the
 sections after explain each.
 
@@ -84,18 +84,17 @@ export const schema = defineSchema(
 
 ```ts
 // 3. an AGENT run inherits its user, narrowed to the entities in play.
-// Pass the MODEL form — { decks: id } — not a hand-built `deck:<id>` string;
-// the engine derives the group from each model's `scope`. The narrowing lives
-// on the client you build, then the provider mounts it.
-const ablo = Ablo({
-  schema,
-  authEndpoint: '/api/ablo-session',
-  scope: { decks: deckId }, // floor: just the deck it's working on
+// You narrow at SESSION-MINT time: your backend calls `sessions.create` with the
+// agent's allowed `syncGroups`, built from each model's scope via the
+// `syncGroup(kind, id)` helper — never a hand-built `deck:<id>` string. The agent's
+// runtime then connects with the minted token.
+const session = await server.sessions.create({
+  agent: { id: agentId },
+  can: { Deck: ['read', 'update'] },
+  syncGroups: [syncGroup('deck', deckId)], // floor: just the deck it's working on
 });
-
-<AbloProvider client={ablo} userId={user.id /* ceiling: the triggering user */}>
-  {children}
-</AbloProvider>;
+// the agent runtime authenticates with the minted token
+const ablo = Ablo({ schema, apiKey: session.token });
 ```
 
 That's the whole surface. The rest of this doc is the *why* behind each line.
@@ -127,11 +126,12 @@ so you pass them in code when you start the run.
 > **One line:** humans subscribe by who they are; agents subscribe by what
 > they've been given.
 
-That's why you never write per-user scope code, but you always pass an agent's
-scope at the call site. A user's org/team/user don't change per request, so
+That's why you never write per-user scope code, but you always choose an agent's
+groups at the dispatch site. A user's org/team/user don't change per request, so
 their scope is a **rule the schema derives automatically**. An agent's reach
 depends on *what it's working on*, which is only knowable at dispatch — so you
-set its `scope` on the client **at the dispatch site, in code**. The schema's
+pass its `syncGroups` **when your backend mints the agent session**
+(`sessions.create({ agent, can, syncGroups })`). The schema's
 only job for entities is to declare *that* a model is
 entity-scopable and *what its group is named* (`scope: 'deck'` → `deck:{id}`);
 it never declares *which* entities a given agent gets. (A human can opt into the
@@ -305,8 +305,9 @@ server, never by the browser.**
 
 The identity your server resolved is carried by the client you build and the
 `userId` prop. In a Next.js app, resolve the user in a Server Component and pass
-it down. Build the client once (the schema, `teamIds`, and any `scope` narrowing
-live here), then hand it to the provider:
+it down. Build the client once (the schema, `teamIds`, and the `apiKey` resolver
+live here; entity narrowing rides the minted session's `syncGroups`), then hand
+it to the provider:
 
 ```ts
 // lib/ablo.ts
@@ -318,7 +319,10 @@ import { schema } from '@/ablo/schema';
 export function makeAblo(user: { teamIds: string[] }) {
   return Ablo({
     schema,
-    authEndpoint: '/api/ablo-session',
+    // The browser holds no secret — the `apiKey` resolver fetches the
+    // short-lived session token your `/api/ablo-session` route minted, and the
+    // client keeps it fresh before expiry.
+    apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
     teamIds: user.teamIds,
   });
 }
@@ -354,7 +358,7 @@ What carries identity — and just as importantly, what does *not* set the bound
 | ------------ | ------------------------------------------------------------------------------------------------ |
 | `userId` prop | App-level participant id, used for app-owned fields and read by your `identityRole` `source`. **Not** the security boundary — the server enforces scope from the authenticated request. |
 | `teamIds` (on the client) | Team ids expanded into team sync groups via your `identityRoles`.                   |
-| `scope` (on the client) | Optional. **Narrows** the subscription to a subset of what auth already allows — it can never widen it. Use it to scope a page to one entity (e.g. `{ decks: 'abc123' }`). |
+| `syncGroups` (at session mint) | Optional. **Narrows** a minted session's subscription to a subset of what auth already allows — it can never widen it. Passed to `sessions.create({ user \| agent, syncGroups })`; build entries with `syncGroup(kind, id)`. Use it to scope an agent (or a focused page's session) to one entity, e.g. `[syncGroup('deck', 'abc123')]`. |
 
 Because the server is the boundary, a client that changes `userId` to another
 user's id does not gain their data — the server resolves and enforces the real
@@ -398,20 +402,20 @@ subset of what its user could see:
 
 ```ts
 // agent run triggered by `user`, working on one document + one deck.
-// The narrowing lives on the client; the provider just mounts it.
-const ablo = Ablo({
-  schema,
-  authEndpoint: '/api/ablo-session',
-  // authority narrowed to just the entities in play (the floor).
-  // Model form — keyed by model, resolved to groups via each model's `scope`.
-  scope: { documents: documentId, decks: deckId },
+// Your backend mints the agent session narrowed to just the entities in play
+// (the floor). Build each group from the model's scope with `syncGroup(kind, id)`.
+const session = await server.sessions.create({
+  agent: { id: agentId },
+  can: { Document: ['read', 'update'], Deck: ['read', 'update'] },
+  syncGroups: [syncGroup('document', documentId), syncGroup('deck', deckId)],
 });
-
-// identity inherited from the triggering user (the ceiling)
-<AbloProvider client={ablo} userId={user.id}>
+// identity (the ceiling) is inherited from the triggering user via your
+// session-mint logic; the agent runtime connects with the minted token.
+const ablo = Ablo({ schema, apiKey: session.token });
 ```
 
-As the run touches more entities its set **accretes** to cover them; it never
+As the run touches more entities, claim or read them and the client auto-enrolls
+in their entity groups — its set **accretes** to cover them; it never
 widens past the user's ceiling, and it carries no standing access to entities it
 isn't working on. The `identityRoles` need no agent-specific entry: the agent
 carries the triggering user's `userId`, so the same `user:{id}` role that scopes
@@ -444,52 +448,55 @@ runs the [Coordinating long agent work](../README.md#coordinating-long-agent-wor
 `claim` loop is, to the scoping layer, that same participant — scoped to the row
 it claimed.
 
-## Narrowing to specific entities — the `scope` setting
-
-A human gets their full membership automatically (`identityRoles`). To narrow a
-session — a page on one deck, or an agent pointed at the entities it's working
-on — set `scope` on the client you build (`Ablo({ schema, scope })`). You give it
-the **model and id(s)**; the engine builds the group string from the model's
-`scope` (Half 2), so you never hand-write `deck:<id>`.
-
-`scope` accepts four shapes, all resolved through the schema:
-
-| You pass | Resolves to | Use it for |
-| --- | --- | --- |
-| `{ decks: deckId }` | `deck:<deckId>` | one entity (a page, a focused agent) |
-| `{ decks: [id1, id2] }` | `deck:<id1>`, `deck:<id2>` | several of one model |
-| `{ decks: deckId, documents: docId }` | `deck:<deckId>`, `document:<docId>` | a mix across models |
-| `[{ type: 'Deck', id: deckId }]` | `deck:<deckId>` | entity refs (e.g. from a list) |
-
-```tsx
-// a page on one deck
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session', scope: { decks: deckId } });
-<AbloProvider client={ablo} userId={user.id} />;
-
-// an agent working across two decks and a document
-const ablo = Ablo({
-  schema,
-  authEndpoint: '/api/ablo-session',
-  scope: { decks: [deckA, deckB], documents: docId },
-});
-<AbloProvider client={ablo} userId={user.id} />;
-```
-
-The key is the **model** (`decks`), the value is **which id(s)** — the `deck:`
-prefix comes from that model's `scope: 'deck'`, never from a string you compose.
-
-> **`scope` means one thing: sync-group scope.** It appears in two places that
-> are the same concept — the model option `scope: 'deck'` (declares a scope root,
-> [Half 2](#half-2--per-model-scope-row--group)) and this `scope` client setting
-> (subscribe to it). The lifecycle filter on [`list()`](./api.md#model-methods) is a separate
-> axis and is named **`state`** (`'live' | 'archived' | 'all'`, GitHub's
-> open/closed/all), precisely so it doesn't share the word.
-
-> **`scope` requests, it never grants.** At connect, the server intersects your
-> requested groups with what the identity is actually allowed (`requested ∩
-> allowed`). So `scope` only ever *narrows* within a participant's ceiling — an
-> agent can't reach a deck its capability doesn't already permit, no matter what
-> it passes. Smaller bootstrap, less fan-out, same server-enforced boundary.
+## Narrowing to specific entities
+
+A human gets their full membership automatically (`identityRoles`). There are
+three ways to narrow a participant to specific entities — a page on one deck, or
+an agent pointed at the entities it's working on. You **never hand-write**
+`deck:<id>`; build groups from the model's `scope` (Half 2) with the typed
+`syncGroup(kind, id)` helper from `@abloatai/ablo/schema`.
+
+1. **At session mint — `syncGroups`.** When your backend mints a session, pass the
+   exact groups it may subscribe to. This is the floor for a delegated agent (and
+   the way to scope a focused page's session):
+
+   ```ts
+   // an agent working across two decks and a document
+   const session = await server.sessions.create({
+     agent: { id: agentId },
+     can: { Deck: ['read', 'update'], Document: ['read'] },
+     syncGroups: [
+       syncGroup('deck', deckA),
+       syncGroup('deck', deckB),
+       syncGroup('document', docId),
+     ],
+   });
+   const ablo = Ablo({ schema, apiKey: session.token });
+   ```
+
+2. **Automatically, on read or claim.** Reading a row (`retrieve`/`get`/
+   `claim.state`) auto-enrolls the client in that row's entity group
+   (**read-interest**), and `claim`-ing it pins a **write-intent** subscription.
+   So an agent's reachable set **accretes** as it works — no extra subscribe call.
+
+3. **Explicitly, for presence — `watch`.** To hold presence on a known set of rows
+   and react to peers, use the WebSocket-only `ablo.<model>.watch(ids, { ttl })`
+   (it returns a participant handle with `.peers`). See
+   [Coordination](./coordination.md).
+
+> **`scope` is the schema model option, not a client setting.** `scope: 'deck'`
+> in `model(...)` declares a scope root ([Half 2](#half-2--per-model-scope-row--group)) —
+> it names the group (`deck:<id>`) that the mechanisms above then subscribe to.
+> There is no `Ablo({ scope })` constructor option. The lifecycle filter on
+> [`list()`](./api.md#model-methods) is a separate axis named **`state`**
+> (`'live' | 'archived' | 'all'`, GitHub's open/closed/all), precisely so it
+> doesn't share the word.
+
+> **Requested groups never grant.** At connect, the server intersects the session's
+> `syncGroups` with what the identity is actually allowed (`requested ∩ allowed`).
+> So `syncGroups` only ever *narrows* within a participant's ceiling — an agent
+> can't reach a deck its capability doesn't already permit, no matter what it
+> passes. Smaller bootstrap, less fan-out, same server-enforced boundary.
 
 ## How this compares — and the best practices it follows
 
@@ -512,7 +519,7 @@ how to reason about it.
   the room/shape and the server signs off, as in
   [Pusher's channel authorization endpoint](https://pusher.com/docs/channels/server_api/authorizing-users/),
   [ElectricSQL **gatekeeper auth**](https://github.com/electric-sql/electric/blob/main/examples/gatekeeper-auth/README.md),
-  and Liveblocks **access tokens**. Ablo's client `scope` setting is the
+  and Liveblocks **access tokens**. Ablo's session-mint `syncGroups` is the
   *narrowing* half of this — but it can only ever shrink the server-derived set,
   never grow it.
 
@@ -529,10 +536,10 @@ The best practices Ablo inherits from that lineage:
 2. **Trusted vs untrusted claims is the whole security argument.** PowerSync draws
    the line precisely: [token parameters are trusted and usable for access
    control; client parameters are not](https://docs.powersync.com/usage/sync-rules/advanced-topics/client-parameters).
-   In Ablo terms, the identity your server vouches for is the *trusted* claim that
-   sets scope; the `userId` prop and the client's `scope` setting are *untrusted
-   client input* — convenient for app-owned fields and narrowing, but never the
-   boundary. This is why changing `userId` in the browser grants nothing.
+   In Ablo terms, the identity your server vouches for — and the session's
+   `syncGroups`, minted server-side — are the *trusted* claims that set scope; the
+   `userId` prop is *untrusted client input* — convenient for app-owned fields, but
+   never the boundary. This is why changing `userId` in the browser grants nothing.
 
 3. **Scope by a hierarchical naming convention, declared once.** Ablo's `kind:id`
    group naming (`org:…` / `team:…` from `identityRoles`, `deck:…` from a model's