@abloatai/ablo 0.59.2 → 0.61.0

package/docs/examples/nextjs.md

@@ -28,6 +28,7 @@ app/
       RecordEditor.tsx        # Client: live updates
 lib/
   ablo.ts                   # Server Ablo client (holds ABLO_API_KEY)
+  sessions.ts               # Server-only scoped-session issuer
   ablo.schema.ts            # shared schema
 ```
 
@@ -36,7 +37,7 @@ There are **two** Ablo clients, and the split is the whole point:
 - **Server** (`lib/ablo.ts`) holds the secret `apiKey` (`sk_`). Used by RSCs,
   Server Actions, and route handlers. Never imported into a client component.
 - **Browser** (`app/providers.tsx`) holds **no secret**. It fetches a
-  short-lived per-user token (`ek_`) from a backend route via `authEndpoint`.
+  short-lived per-user token (`ek_`) from a backend route via `session.endpoint`.
 
 Skipping the browser half is the most common setup mistake — the client then
 has no credential and the engine fails to initialize with `session_expired`.
@@ -57,6 +58,19 @@ export const ablo = Ablo({
 });
 ```
 
+```ts
+// lib/sessions.ts — server-only
+import 'server-only';
+
+import Sessions from '@abloatai/ablo/sessions';
+import { schema } from './ablo.schema';
+
+export const sessions = Sessions({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+```
+
 ## Session Route
 
 The browser can't hold `sk_`, so a backend route mints a scoped, short-lived
@@ -67,80 +81,33 @@ from the request body.
 
 ```ts
 // app/api/ablo-session/route.ts
-import { ablo } from '@/lib/ablo';
+import { sessions } from '@/lib/sessions';
 import { getCurrentUser } from '@/auth';
-import { headers } from 'next/headers';
-import {
-  credentialEndpointErrorSchema,
-  credentialEndpointSuccessSchema,
-} from '@abloatai/ablo/auth';
-
-const noStore = { 'Cache-Control': 'no-store' };
-
-export async function POST(request: Request) {
-  if (!(await isSameOrigin(request))) {
-    return Response.json(
-      credentialEndpointErrorSchema.parse({
-        error: { code: 'origin_mismatch', message: 'Cross-origin mint rejected' },
-      }),
-      { status: 403, headers: noStore },
-    );
-  }
-
-  const user = await getCurrentUser();
-  if (!user) {
-    return Response.json(
-      credentialEndpointErrorSchema.parse({
-        error: { code: 'session_expired' },
-      }),
-      { status: 401, headers: noStore },
-    );
-  }
-
-  // Query your membership table now—not when the login session was created.
-  // The helper reads the active workspace from server-side session state and
-  // returns null when the membership is stale or revoked.
-  const scope = await authorizeActiveWorkspace(user.id);
-  if (!scope) {
-    return Response.json(
-      credentialEndpointErrorSchema.parse({
-        error: { code: 'policy_denied', message: 'Workspace membership is stale or revoked' },
-      }),
-      { status: 403, headers: noStore },
-    );
-  }
-
-  const { token, expiresAt } = await ablo.sessions.create({
-    user: { id: user.id },
-    syncGroups: scope.syncGroups,
-    can: { records: ['read', 'create', 'update'] },
-  });
-  return Response.json(
-    credentialEndpointSuccessSchema.parse({
-      token,
-      expiresAt,
-      credentialKind: 'ephemeral',
-    }),
-    { headers: noStore },
-  );
-}
 
-async function isSameOrigin(request: Request): Promise<boolean> {
-  const origin = request.headers.get('origin');
-  if (!origin) return request.headers.get('sec-fetch-site') !== 'cross-site';
-  const host = (await headers()).get('host');
-  return host !== null && new URL(origin).host === host;
-}
+export const POST = sessions.handler({
+  authenticate: () => getCurrentUser(),
+  async grant({ principal: user }) {
+    // Query your membership table now—not when the login session was created.
+    const scope = await authorizeActiveWorkspace(user.id);
+    if (!scope) return null;
+
+    return {
+      user: { id: user.id },
+      groups: scope.groups,
+      can: { records: ['read', 'create', 'update'] },
+    };
+  },
+});
 ```
 
 `authorizeActiveWorkspace` is application code: it must query the authoritative
-membership store and return server-derived sync groups. If fifteen-minute token
+membership store and return server-derived groups. If fifteen-minute token
 expiry is too slow for your revocation requirements, mint a shorter
 `ttlSeconds` and revoke active sessions when membership changes.
 
 ## Provider
 
-The browser client points `authEndpoint` at that route and is handed to
+The browser client points `session.endpoint` at that route and is handed to
 `<AbloProvider>` as an instance. Build it once at module scope so the socket
 isn't torn down on every render.
 
@@ -154,7 +121,7 @@ import { schema } from '@/lib/ablo.schema';
 
 const ablo = Ablo({
   schema,
-  authEndpoint: '/api/ablo-session',
+  session: { endpoint: '/api/ablo-session' },
 });
 
 export function Providers({ children }: { children: React.ReactNode }) {

package/docs/examples/scoped-agent.md

@@ -59,21 +59,22 @@ never does), then hand the short-lived token to the browser client:
 ```ts
 // server — mints a scoped agent session for one workspace
 import Ablo from '@abloatai/ablo';
+import Sessions from '@abloatai/ablo/sessions';
 import { syncGroup } from '@abloatai/ablo/schema';
 import { schema } from './schema';
 
-const server = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
 
 export async function mintProjectAgentSession(
   workspaceId: string,
   agentId: string,
   requestingUserId: string,
 ) {
-  const { token } = await server.sessions.create({
+  const { token } = await sessions.create({
     agent: { id: agentId },
     onBehalfOf: { user: { id: requestingUserId } },
     can: { records: ['read', 'update'] }, // operation allowlist for this run
-    syncGroups: [syncGroup('workspace', workspaceId)], // narrowed to just this workspace
+    groups: [syncGroup('workspace', workspaceId)], // narrowed to just this workspace
   });
   return token;
 }

package/docs/examples/server-agent.md

@@ -19,6 +19,7 @@ fresh row, then hands it to you — so two writers serialize instead of clobberi
 
 ```ts
 import Ablo from '@abloatai/ablo';
+import Sessions from '@abloatai/ablo/sessions';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
@@ -29,17 +30,17 @@ const schema = defineSchema({
   }),
 });
 
-const control = Ablo({
+const sessions = Sessions({
   schema,
   apiKey: process.env.ABLO_API_KEY,
 });
 
 async function clientForWorker(workerId: string) {
-  const { token } = await control.sessions.create({
+  const session = await sessions.create({
     agent: { id: workerId },
     can: { records: ['read', 'update'] },
   });
-  return Ablo({ schema, apiKey: token, transport: 'http' });
+  return Ablo({ schema, session, transport: 'http' });
 }
 
 export async function completeTask(recordId: string, workerId: string) {

package/docs/groups.md

@@ -38,16 +38,15 @@ write. The agent never persists work built on a premise it can no longer see.
 
 ## How you hear about it
 
-Three channels carry "something changed", and they answer three different
-questions. Pick by the question you have.
+Three channels answer three different coordination questions. Pick by the
+question you have.
 
 ```ts
 // A screen that stays current.
 ablo.records.onChange((docs) => render(docs));
 
-// Who else is in here, and what are they holding.
-await using room = await ablo.records.join(documentIds, { ttl: '5m' });
-room.peers;
+// In React: who else is visible on this client's scoped groups?
+const peers = usePeers({ records: documentId });
 
 // Stop this write if the thing I read moved while I composed it.
 const record = await ablo.records.read({ id: 's-1' });
@@ -58,12 +57,12 @@ await ablo.blocks.update({ id, data, reads: [record] });
 | Question | Channel | Arrives |
 | --- | --- | --- |
 | What do the rows say right now? | `onChange` | As deltas land, on the socket |
-| Who else is working here? | `join`, then `room.peers` and `room.claims` | As participants come and go, on the socket |
+| Who else is working here? | `usePeers` over the session/client groups | As participants connect, disconnect, or change activity |
 | Did the premise for **this** write move? | `reads` on the write | On that write's receipt, before it applies |
 
-`onChange` and `join` need a live socket, so they are available on the default
-WebSocket client. `reads` rides the commit, so it reaches a socketless actor over
-HTTP too. The row returned by `read` privately carries its model, id, and
+`onChange` and `usePeers` use the reactive client's socket. `reads` rides the
+commit, so it reaches a socketless actor over HTTP too. The row returned by
+`read` privately carries its model, id, and
 watermark; passing that row in `reads` is enough to protect a later write. Ablo
 does not retain the row contents as read evidence.
 
@@ -184,6 +183,6 @@ them coarse everywhere else.
   [`concurrency-convention.md`](./concurrency-convention.md) (§4 and §5).
 - **The mechanics**, the three coordination blocks underneath, are
   [`coordination.md`](./coordination.md).
-- **`join` and presence**, the participant half of the table above, are
-  [`coordination.md`](./coordination.md) for the claim stream and
-  [`react.md`](./react.md) for `useJoin`.
+- **Presence** is read with `usePeers`; active exclusions remain on the
+  `claim` namespace. See [`react.md`](./react.md) and
+  [`coordination.md`](./coordination.md).

package/docs/identity.md

@@ -51,10 +51,13 @@ secret mints a replacement, least-privilege agent credential with the schema-
 typed grant:
 
 ```ts
-const session = await control.sessions.create({
+import Sessions from '@abloatai/ablo/sessions';
+
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
+const session = await sessions.create({
   agent: { id: agentId },
   can: { records: ['read', 'update'] },
-  syncGroups: [syncGroup('workspace', workspaceId)],
+  groups: [syncGroup('workspace', workspaceId)],
 });
 ```
 
@@ -87,7 +90,7 @@ runnable place, so the concepts below have code to attach to.
 
 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
-optional `syncGroups` at session-mint time (narrowing). Read the three blocks first —
+optional `groups` at session-mint time (narrowing). Read the three blocks first —
 a human gets their `org` / `team` scope, an agent gets one `workspace` — then the
 sections after explain each.
 
@@ -135,16 +138,16 @@ export const schema = defineSchema(
 ```ts
 // 3. an AGENT run inherits its user, narrowed to the entities in play.
 // 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
+// agent's allowed groups, built from each model's scope via the
 // `syncGroup(kind, id)` helper — never a hand-built `workspace:<id>` string. The agent's
 // runtime then connects with the minted token.
-const session = await server.sessions.create({
+const session = await sessions.create({
   agent: { id: agentId },
   can: { Workspace: ['read', 'update'] },
-  syncGroups: [syncGroup('workspace', workspaceId)], // floor: just the workspace it's working on
+  groups: [syncGroup('workspace', workspaceId)], // floor: just the workspace it's working on
 });
 // the agent runtime authenticates with the minted token
-const ablo = Ablo({ schema, apiKey: session.token });
+const ablo = Ablo({ schema, session });
 ```
 
 That's the whole surface. The rest of this doc is the *why* behind each line.
@@ -180,8 +183,8 @@ 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
-pass its `syncGroups` **when your backend mints the agent session**
-(`sessions.create({ agent, can, syncGroups })`). The schema's
+pass its `groups` **when your backend mints the agent session**
+(`sessions.create({ agent, can, groups })`). The schema's
 only job for entities is to declare *that* a model is
 entity-scopable and *what its group is named* (`scope: 'workspace'` → `workspace:{id}`);
 it never declares *which* entities a given agent gets. (A human can opt into the
@@ -224,7 +227,7 @@ stays in the customer's org:
 ```ts
 const server = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-await server.sessions.create({
+await sessions.create({
   user: { id: userId },
   organizationId, // DATA → this customer's RLS-isolated organization
   can: { records: ['read', 'update'] },
@@ -405,7 +408,7 @@ 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 the `apiKey` resolver
-live here; entity narrowing rides the minted session's `syncGroups`), then hand
+live here; entity narrowing rides the minted session's `groups`), then hand
 it to the provider:
 
 ```ts
@@ -418,10 +421,10 @@ import { schema } from '@/ablo/schema';
 export function makeAblo(user: { teamIds: string[] }) {
   return Ablo({
     schema,
-    // The browser holds no secret — `authEndpoint` points at the route that
+    // The browser holds no secret — `session.endpoint` points at the route that
     // mints the short-lived session token, and the client keeps it fresh
     // before expiry.
-    authEndpoint: '/api/ablo-session',
+    session: { endpoint: '/api/ablo-session' },
     teamIds: user.teamIds,
   });
 }
@@ -457,7 +460,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`.                   |
-| `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('workspace', 'abc123')]`. |
+| `groups` (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, groups })`; build entries with `syncGroup(kind, id)`. Use it to scope an agent (or a focused page's session) to one entity, e.g. `[syncGroup('workspace', '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
@@ -503,15 +506,15 @@ subset of what its user could see:
 // agent run triggered by `user`, working on one document + one workspace.
 // 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({
+const session = await sessions.create({
   agent: { id: agentId },
   onBehalfOf: { user: { id: triggeringUser.id } },
   can: { Document: ['read', 'update'], Workspace: ['read', 'update'] },
-  syncGroups: [syncGroup('document', recordId), syncGroup('workspace', workspaceId)],
+  groups: [syncGroup('document', recordId), syncGroup('workspace', workspaceId)],
 });
 // 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 });
+const ablo = Ablo({ schema, session });
 ```
 
 As the run touches more entities, claim or read them and the client auto-enrolls
@@ -555,22 +558,22 @@ an agent pointed at the entities it's working on. You **never hand-write**
 `workspace:<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
+1. **At session mint — `groups`.** 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 workspaces and a document
-   const session = await server.sessions.create({
+   const session = await sessions.create({
      agent: { id: agentId },
      can: { Workspace: ['read', 'update'], Document: ['read'] },
-     syncGroups: [
+     groups: [
        syncGroup('workspace', collectionA),
        syncGroup('workspace', collectionB),
        syncGroup('document', docId),
      ],
    });
-   const ablo = Ablo({ schema, apiKey: session.token });
+   const ablo = Ablo({ schema, session });
    ```
 
 2. **Automatically, on read or claim.** Reading a row (`get`/
@@ -578,10 +581,11 @@ an agent pointed at the entities it's working on. You **never hand-write**
    (**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 — `join`.** To hold presence on a known set of rows
-   and react to peers, use the WebSocket-only `ablo.<model>.join(ids, { ttl })`
-   (it returns a participant handle with `.peers`). See
-   [Coordination](./coordination.md).
+3. **Presence follows those same groups.** A reactive client announces one
+   participant on its connection; `usePeers(scope)` filters the roster already
+   visible through the session and connection groups. There is no second
+   membership lease or participant handle. Use `claim` separately when work needs
+   exclusion. See [React](./react.md#usepeers-read-only-presence).
 
 > **`groups.root` is the schema model option, not a client setting.**
 > `groups: { root: 'workspace' }` in `model(...)` declares a scope root
@@ -593,8 +597,8 @@ an agent pointed at the entities it's working on. You **never hand-write**
 > 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
+> requested groups with what the identity is actually allowed (`requested ∩ allowed`).
+> So `groups` only ever *narrows* within a participant's ceiling — an agent
 > can't reach a workspace its capability doesn't already permit, no matter what it
 > passes. Smaller bootstrap, less fan-out, same server-enforced boundary.
 
@@ -619,7 +623,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 session-mint `syncGroups` is the
+  and Liveblocks **access tokens**. Ablo's session-mint `groups` is the
   *narrowing* half of this — but it can only ever shrink the server-derived set,
   never grow it.
 
@@ -637,7 +641,7 @@ The best practices Ablo inherits from that lineage:
    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 — and the session's
-   `syncGroups`, minted server-side — are the *trusted* claims that set scope; the
+   `groups`, 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.
 

package/docs/integration-guide.md

@@ -30,7 +30,6 @@ The normal integration is one client:
 
 ```ts
 import Ablo from '@abloatai/ablo';
-import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 ```
 
@@ -183,7 +182,7 @@ import { schema } from '@/ablo/schema';
 // from your session route (see below) and refreshes it before expiry.
 export const ablo = Ablo({
   schema,
-  authEndpoint: '/api/ablo-session',
+  session: { endpoint: '/api/ablo-session' },
 });
 ```
 
@@ -203,29 +202,24 @@ The session route mints the scoped token server-side, where the API key lives:
 
 ```ts
 // app/api/ablo-session/route.ts
-import Ablo from '@abloatai/ablo';
+import Sessions from '@abloatai/ablo/sessions';
 import { schema } from '@/ablo/schema';
 import { auth } from '@/auth';
 
 export const runtime = 'nodejs';
 
-const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
 
-export async function POST() {
-  const session = await auth(); // your own auth — returns the signed-in user
-  const { token, expiresAt } = await sync.sessions.create({
-    user: { id: session.userId },
+export const POST = sessions.handler({
+  async authenticate() {
+    const session = await auth();
+    return session?.user ?? null;
+  },
+  grant: ({ principal: user }) => ({
+    user: { id: user.id },
     can: { records: ['read', 'update'] },
-  });
-  return Response.json(
-    credentialEndpointSuccessSchema.parse({
-      token,
-      expiresAt,
-      credentialKind: 'ephemeral',
-    }),
-    { headers: { 'Cache-Control': 'no-store' } },
-  );
-}
+  }),
+});
 ```
 
 ### Why two credential shapes

package/docs/options.md

@@ -12,8 +12,10 @@ import { schema } from './ablo/schema';
 export const ablo = Ablo({ schema });
 ```
 
-These options configure the stateless HTTP client exported by the package root.
-For a live human interface, use the [React guide](./react.md).
+These options configure the package-root coordination client. API-key clients
+use HTTP; session clients use one multiplexed WebSocket by default. For a live
+human interface with a local graph, use the [React guide](./react.md). See
+[Transports](./transports.md) for the lifecycle and selection rules.
 
 ## schema
 
@@ -30,26 +32,55 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 ```
 
 Use a resolver for credentials that rotate. Return `null` when the login has
-ended; throw when credential resolution failed temporarily. Do not pass both
-`apiKey` and `authEndpoint`.
+ended; throw when credential resolution failed temporarily. Do not combine it
+with another credential option.
 
-## authEndpoint
+## session
 
-A same-origin URL that mints a short-lived credential, or an async credential
-resolver. The client sends a `POST` with cookies included and renews the token
-when needed.
+A scoped session returned by the server-only `Sessions(...).create()` issuer.
+Pass the resource
+directly for bounded work, or pass a provider that re-mints the same logical
+actor for a long-running client:
 
 ```ts
-const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+import Sessions from '@abloatai/ablo/sessions';
+
+const sessions = Sessions({ schema, apiKey: process.env.ABLO_API_KEY });
+const session = await sessions.create({
+  agent: { id: workerId },
+  can: { records: ['read', 'update'] },
+});
+
+const worker = Ablo({ schema, session });
+```
+
+Do not extract `session.token` into `apiKey`; the session is the public handoff.
+A provider is cached until its returned session approaches `expiresAt`, so HTTP
+bootstrap and WebSocket connection setup do not mint duplicate credentials.
+
+In a browser, name the application-owned route that mints the signed-in user's
+session. Endpoint tuning belongs inside the same option:
+
+```ts
+const ablo = Ablo({
+  schema,
+  session: {
+    endpoint: '/api/ablo-session',
+    timeoutMs: 10_000,
+    // allowCrossOrigin: true,
+  },
+});
 ```
 
-Use this instead of placing a private API key in browser code.
+The client sends a cookie-bearing `POST`, validates the response, and renews
+before expiry. Cross-origin minting is off by default and should be enabled only
+after configuring CORS and CSRF protection.
 
 ## authToken
 
 A bearer token the caller already holds. This is mainly for self-hosted or
 custom authentication layers. Hosted applications normally use `apiKey` or
-`authEndpoint`.
+`session`.
 
 ## baseURL
 
@@ -68,7 +99,7 @@ local hosts.
 
 Allows a credential-bearing client to run in a browser. Defaults to `false`.
 
-Private API keys must not ship to browsers. Prefer `authEndpoint`; enable this
+Private API keys must not ship to browsers. Prefer `session.endpoint`; enable this
 option only when the browser receives a narrowly scoped session credential or
 all traffic passes through a controlled server proxy.
 
@@ -77,19 +108,6 @@ all traffic passes through a controlled server proxy.
 A custom `fetch` implementation for tests, proxies, or runtimes without the
 standard global implementation.
 
-## authTimeoutMs
-
-The deadline in milliseconds for a request to `authEndpoint`. Defaults to
-`10000`. This is separate from `timeoutMs`, which covers ordinary Ablo API
-requests.
-
-## allowCrossOriginAuthEndpoint
-
-Allows `authEndpoint` to use a different origin. Defaults to `false`.
-
-Keep the default unless the credential-minting service intentionally lives on a
-different trusted origin.
-
 ## bootstrapBaseUrl
 
 Overrides the URL used for credential exchange and bootstrap. Most applications
@@ -108,7 +126,7 @@ const ablo = Ablo({
 ```
 
 Do not use this option to duplicate the credential header; authentication is
-owned by `apiKey`, `authEndpoint`, or `authToken`.
+owned by `session`, `apiKey`, or `authToken`.
 
 ## defaultQuery
 
@@ -160,9 +178,10 @@ workflow or deployment lanes.
 
 ## transport
 
-The package-root client defaults to request/response HTTP. Select
-`transport: 'websocket'` for a resident agent that needs pushed coordination;
-the model, commit, claim, and context vocabulary stays unchanged.
+Transport follows the configured identity. `apiKey` and `authToken` clients use
+request/response HTTP. `session` clients use one reconnecting WebSocket. Pass
+`transport: 'http'` only when bounded work needs a scoped session identity but
+must not hold a socket. The model, commit, claim, and context API stays unchanged.
 
 Local materialized state and reactive reads still belong to the human client
 described in the [React guide](./react.md); selecting WebSocket here adds a
@@ -172,3 +191,35 @@ carrier, not the human materializer.
 
 The deadline in milliseconds for an Ablo HTTP request. Defaults to `30000`. Pass
 `0` only when the surrounding runtime already enforces a deadline.
+
+## groups
+
+The initial groups observed by a WebSocket client. This can narrow what the
+connection follows, but it cannot widen the authority granted by
+`sessions.create({ groups })`.
+
+## collaborationEvents
+
+Application-defined WebSocket event names accepted by `subscribe()`.
+
+## cursorStore
+
+Persistent storage for the WebSocket observation cursor, used to resume after a
+disconnect without replaying already-consumed events.
+
+## cursorKey
+
+The stable name used for the persisted observation cursor. Defaults to
+`default`.
+
+## reconnectDelay
+
+Initial WebSocket reconnect delay in milliseconds.
+
+## maxReconnectDelay
+
+Maximum WebSocket reconnect delay in milliseconds after backoff.
+
+## connectTimeoutMs
+
+The deadline in milliseconds for establishing a WebSocket connection.