@abloatai/ablo 0.9.0 → 0.9.2

package/docs/identity.md

@@ -1,7 +1,7 @@
 # Identity & Sync Groups
 
 This is the doc the Quickstart skips: **who is connecting, and which slice
-of shared state do they get?** If you've wired `<AbloProvider schema={schema}>`
+of shared state do they get?** If you've wired `<AbloProvider client={ablo}>`
 and wondered where org / team / user actually come from — start here.
 
 ## Ablo does not do auth
@@ -37,9 +37,9 @@ 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 an
-optional `syncGroups` prop (narrowing). Read the three blocks first — a human
-gets their `org` / `team` scope, an agent gets one `deck` — then the sections
-after explain each.
+optional `scope` setting on the client (narrowing). Read the three blocks first —
+a human gets their `org` / `team` scope, an agent gets one `deck` — then the
+sections after explain each.
 
 ```ts
 // 1. src/ablo/schema.ts — map identity → groups, and anchor each model to a group
@@ -74,23 +74,28 @@ export const schema = defineSchema(
 ```
 
 ```tsx
-// 2. app/providers.tsx — a HUMAN gets their full org / team scope
-<AbloProvider schema={schema} userId={user.id} teamIds={user.teamIds}>
+// 2. app/providers.tsx — a HUMAN gets their full org / team scope.
+// teamIds is set on the client you build (Ablo({ schema, teamIds: user.teamIds })),
+// not passed to the provider; the provider just takes that client.
+<AbloProvider client={ablo} userId={user.id}>
   {children}
 </AbloProvider>
 ```
 
-```tsx
+```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`.
-<AbloProvider
-  schema={schema}
-  userId={user.id}                // ceiling: the triggering user
-  scope={{ decks: deckId }}       // floor: just the deck it's working on
->
+// 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
+});
+
+<AbloProvider client={ablo} userId={user.id /* ceiling: the triggering user */}>
   {children}
-</AbloProvider>
+</AbloProvider>;
 ```
 
 That's the whole surface. The rest of this doc is the *why* behind each line.
@@ -126,8 +131,8 @@ 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
 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` **at the call site, in code**. The schema's only job for
-entities is to declare *that* a model is
+set its `scope` on the client **at the dispatch site, in code**. 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
 same runtime narrowing — a page scoped to one deck — but by default a human's
@@ -298,45 +303,62 @@ server, never by the browser.**
 
 ## Wiring the provider
 
-The provider props carry the identity your server resolved. In a Next.js app,
-resolve the user in a Server Component and pass it down:
+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:
+
+```ts
+// lib/ablo.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from '@/ablo/schema';
+
+// Build the client from the identity your server already resolved.
+// teamIds → team sync groups via identityRoles.
+export function makeAblo(user: { teamIds: string[] }) {
+  return Ablo({
+    schema,
+    authEndpoint: '/api/ablo-session',
+    teamIds: user.teamIds,
+  });
+}
+```
 
 ```tsx
-// app/providers.tsx — 'use client'
+// app/providers.tsx
+'use client';
+
+import { useMemo } from 'react';
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo/schema';
+import { makeAblo } from '@/lib/ablo';
 
 export function Providers({
   children,
-  user,            // { id, teamIds } — resolved server-side from YOUR auth
+  user, // { id, teamIds } — resolved server-side from YOUR auth
 }: {
   children: React.ReactNode;
   user: { id: string; teamIds: string[] };
 }) {
+  const ablo = useMemo(() => makeAblo(user), [user.id]);
   return (
-    <AbloProvider
-      schema={schema}
-      userId={user.id}
-      teamIds={user.teamIds}
-      fallback={<AppSkeleton />}
-    >
+    <AbloProvider client={ablo} userId={user.id} fallback={<AppSkeleton />}>
       {children}
     </AbloProvider>
   );
 }
 ```
 
-What each identity-related prop does — and just as importantly, does *not* do:
+What carries identity — and just as importantly, what does *not* set the boundary:
 
-| Prop         | Purpose                                                                                          |
+| Where        | Purpose                                                                                          |
 | ------------ | ------------------------------------------------------------------------------------------------ |
-| `userId`     | 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`    | Team ids expanded into team sync groups via your `identityRoles`.                                |
-| `syncGroups` | 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. `['deck:abc123']`). |
+| `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' }`). |
 
 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
-identity on the connection. The props are how your app *tells* Ablo who it
+identity on the connection. These are how your app *tells* Ablo who it
 already authenticated, not how it *proves* it.
 
 ## Agents are participants too
@@ -374,16 +396,19 @@ decks:     model({ /* … */ }, {}, { orgScoped: true, scope: 'deck' }),
 Then a run subscribes only to the entity groups for the rows it works on — a
 subset of what its user could see:
 
-```tsx
-// agent run triggered by `user`, working on one document + one deck
-<AbloProvider
-  schema={schema}
-  // identity inherited from the triggering user (the ceiling)
-  userId={user.id}
+```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 }}
->
+  scope: { documents: documentId, decks: deckId },
+});
+
+// identity inherited from the triggering user (the ceiling)
+<AbloProvider client={ablo} userId={user.id}>
 ```
 
 As the run touches more entities its set **accretes** to cover them; it never
@@ -419,13 +444,13 @@ 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` prop
+## 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 — pass `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>`.
+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:
 
@@ -438,14 +463,16 @@ group string from the model's `scope` (Half 2), so you never hand-write
 
 ```tsx
 // a page on one deck
-<AbloProvider schema={schema} userId={user.id} scope={{ decks: deckId }} />
+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
-<AbloProvider
-  schema={schema}
-  userId={user.id}
-  scope={{ decks: [deckA, deckB], documents: docId }}
-/>
+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:`
@@ -453,8 +480,8 @@ 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` prop (subscribe
-> to it). The lifecycle filter on [`list()`](./api.md#model-methods) is a separate
+> [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.
 
@@ -485,9 +512,9 @@ 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 `syncGroups` prop is the *narrowing*
-  half of this — but it can only ever shrink the server-derived set, never grow
-  it.
+  and Liveblocks **access tokens**. Ablo's client `scope` setting is the
+  *narrowing* half of this — but it can only ever shrink the server-derived set,
+  never grow it.
 
 The best practices Ablo inherits from that lineage:
 
@@ -503,9 +530,9 @@ 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 is the *trusted* claim that
-   sets scope; the provider's `userId` / `scope` props 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.
+   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.
 
 3. **Scope by a hierarchical naming convention, declared once.** Ablo's `kind:id`
    group naming (`org:…` / `team:…` from `identityRoles`, `deck:…` from a model's

package/docs/index.md

@@ -42,7 +42,7 @@ Three things stay true no matter how you use Ablo:
 - [Quickstart](./quickstart.md) — Make your first schema-backed write.
 - [Schema Contract](./schema-contract.md) — One schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
 - [CLI & Migrations](./cli.md) — `init` / `migrate` / `push` / `generate`, the shared Zod→Postgres type map, and structured migration errors.
-- [Identity & Sync Groups](./identity.md) — Bring your own auth; tell Ablo who's connecting and how org / team / user map to sync-group scope.
+- [Identity & Sync Groups](./identity.md) — Use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
 - [Integration Guide](./integration-guide.md) — Choose Ablo-managed state, Data Source, React, multiplayer, and agent patterns.
 - [Guarantees](./guarantees.md) — What confirmed writes, stale checks, and claims guarantee.
 - [Interaction Model](./interaction-model.md) — The schema, claim, update, confirmation loop.

package/docs/integration-guide.md

@@ -170,17 +170,49 @@ export const ablo = Ablo({
 ```
 
 Browser apps should use the React provider or a scoped session token, not a
-server API key in the bundle.
+server API key in the bundle. Build the client first, then hand it to the
+provider — `AbloProvider` takes `{ client, userId?, onError?, fallback? }`, and
+nothing else (`schema`, `teamIds`, `scope`, and `authEndpoint` all live on the
+client now).
+
+```tsx
+// src/ablo-client.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from '@/ablo/schema';
+
+// The browser never holds the API key. The client mints a short-lived token
+// from your session route (see below) and refreshes it before expiry.
+export const ablo = Ablo({ schema, authEndpoint: '/api/ablo-session' });
+```
 
 ```tsx
 // app/providers.tsx
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo/schema';
+import { ablo } from '@/ablo-client';
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return <AbloProvider schema={schema}>{children}</AbloProvider>;
+  return <AbloProvider client={ablo}>{children}</AbloProvider>;
+}
+```
+
+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 { schema } from '@/ablo/schema';
+import { auth } from '@/auth';
+
+export const runtime = 'nodejs';
+
+const sync = Ablo({ 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 } = await sync.sessions.create({ user: { id: session.userId } });
+  return Response.json({ token });
 }
 ```
 
@@ -214,10 +246,11 @@ refreshes before expiry.
 ## 3. Read State
 
 Reads come in two flavors, and you pick based on whether you can wait.
-`retrieve(id)` and `list({ where })` hit the server (and hydrate the local
-store) — they're async, so you `await` them. `get(id)`, `getAll({ where })`,
-and `getCount({ where })` read the already-synced local graph synchronously, so
-they're the ones you call in render.
+`retrieve({ id })` and `list({ where })` hit the server (and hydrate the local
+store) — they're async, so you `await` them. `get(id)` (positional),
+`getAll({ where })`, and `getCount({ where })` read the already-synced local
+graph synchronously, so they're the ones you call in render — and the ones you
+use inside a `useAblo` selector, never the async `retrieve`/`list`.
 
 Use `retrieve` when the row may not be local yet — it fetches from the server
 and waits.
@@ -345,47 +378,41 @@ For the full Python shape, see
 
 ## 7. Data Source Endpoint
 
-Use a Data Source when your app database remains the source of truth.
+Use a Data Source when your app database remains the source of truth. Wire the
+route with `dataSourceNext` and an adapter — `prismaDataSource(prisma, schema)`
+or `drizzleDataSource(db, schema)`. You don't hand-write `commit`; the adapter
+owns transactional commit, idempotency, and reads.
 
 ```ts
 // app/api/ablo/source/route.ts
-import { dataSource } from '@abloatai/ablo';
+import { dataSourceNext } from '@abloatai/ablo/source/next';
+import { prismaDataSource } from '@abloatai/ablo/source';
 import { schema } from '@/ablo/schema';
-import { db } from '@/db';
-
-export const POST = dataSource({
-  schema,
-  apiKey: process.env.ABLO_API_KEY,
+import { prisma } from '@/db';
 
-  authorize() {
-    return { db };
-  },
+export const runtime = 'nodejs';
 
-  async commit({ operations, clientTxId, context }) {
-    const rows = await context.auth.db.transaction(async (tx) => {
-      await tx.idempotency.upsert({ key: clientTxId });
-      return applyOperations(tx, operations);
-    });
+export const { POST } = dataSourceNext({
+  schema,
+  apiKey: process.env.ABLO_API_KEY!,
+  adapter: prismaDataSource(prisma, schema),
+});
+```
 
-    return { rows };
-  },
+With Drizzle, pass `drizzleDataSource(db, schema)` instead — the adapter takes
+your Drizzle `db` and the Ablo `schema` (not your table objects):
 
-  reports: {
-    async load({ id, context }) {
-      return context.auth.db.report.findUnique({ where: { id } });
-    },
+```ts
+import { drizzleDataSource } from '@abloatai/ablo/source/drizzle';
 
-    async list({ query, context }) {
-      return context.auth.db.report.findMany({
-        take: query.limit ?? 100,
-      });
-    },
-  },
+export const { POST } = dataSourceNext({
+  schema,
+  apiKey: process.env.ABLO_API_KEY!,
+  adapter: drizzleDataSource(db, schema),
 });
 ```
 
-Ablo needs your Data Source endpoint and API key. External writes can be
-reported through an optional `events` handler on the same route. Your app
+Ablo needs your Data Source endpoint and API key. Your app
 stores one Ablo credential:
 
 ```bash
@@ -404,16 +431,18 @@ which a human might touch the same row. Wrap that work in a claim. 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 of clobbering.
 
-```ts
-const report = await ablo.weatherReports.retrieve({ id: reportId });
-if (!report) return;
+A claim is a disposable handle (`await using`), not a callback: read the fresh
+row off `claim.data`, do your work, and the handle auto-releases when it leaves
+scope.
 
+```ts
 await using claim = await ablo.weatherReports.claim({
   id: reportId,
-  wait: false,
   action: 'forecasting',
 });
 const claimed = claim.data;
+if (!claimed) return;
+
 await ablo.weatherReports.update({
   id: claimed.id,
   data: { status: 'ready', forecast: await getForecast(claimed) },
@@ -464,17 +493,19 @@ them.
 
 ## Method Cheatsheet
 
-| Method                       | Use it for                                                                  |
-| ---------------------------- | --------------------------------------------------------------------------- |
-| `retrieve(id)`               | Async read of one row from the server (await it).                           |
-| `list({ where })`           | Async read of many rows from the server (await it).                         |
-| `get(id)`                    | Synchronous local read of one synced row (use in render).                   |
-| `getAll({ where })`         | Synchronous local read of many synced rows.                                 |
-| `getCount({ where })`       | Synchronous local count of synced rows.                                     |
-| `create(data, options?)`     | Create through the model client.                                            |
-| `update(id, data, options?)` | Update through the model client.                                            |
-| `delete(id, options?)`       | Delete through the model client.                                            |
-| `claim.state({ id })`            | See who is currently working on a row (synchronous).                       |
-| `claim(id, work, options?)`  | Wait for your turn, re-read, and hold the row while `work` runs.            |
-
-Keep first integrations on the model methods above.
+| Method                                 | Use it for                                                                       |
+| -------------------------------------- | -------------------------------------------------------------------------------- |
+| `retrieve({ id })`                     | Async read of one row from the server (await it).                                |
+| `list({ where })`                      | Async read of many rows from the server (await it).                              |
+| `get(id)`                              | Synchronous local read of one synced row (positional id; use in render).         |
+| `getAll({ where })`                    | Synchronous local read of many synced rows.                                      |
+| `getCount({ where })`                  | Synchronous local count of synced rows.                                          |
+| `create({ data, id? })`                | Create through the model client.                                                 |
+| `update({ id, data, ...opts })`        | Update through the model client.                                                 |
+| `delete({ id, ...opts })`              | Delete through the model client.                                                 |
+| `claim.state({ id })`                  | See who is currently working on a row (synchronous).                             |
+| `claim({ id, action?, ttl? })`         | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
+
+Keep first integrations on the model methods above. Every mutation and
+server-read verb takes one options object; only the synchronous `get(id)` stays
+positional.

package/docs/react.md

@@ -14,6 +14,27 @@ The React bindings ship with the main package — no extra install.
 import { useAblo } from '@abloatai/ablo/react';
 ```
 
+## Building the client
+
+You build the Ablo client once — that's where the schema, the session endpoint,
+and connection config live — then hand it to the provider. The provider takes
+the already-built `client`; it no longer takes `schema`, `url`, `apiKey`, etc.
+as props. This mirrors Stripe's `<Elements stripe={stripePromise}>`: construct
+the thing, then pass it.
+
+```ts
+// lib/ablo.ts
+import Ablo from '@abloatai/ablo';
+import { schema } from '@/ablo/schema';
+
+// The browser never holds your API key. It mints a short-lived session token
+// from your own server route (see Identity below).
+export const ablo = Ablo({
+  schema,
+  authEndpoint: '/api/ablo-session',
+});
+```
+
 ## AbloProvider
 
 Mount it once near the root of your tree. It owns the connection, the local
@@ -23,48 +44,38 @@ pool, and the engine lifecycle; everything below it reads with `useAblo`.
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo/schema';
+import { ablo } from '@/lib/ablo';
 
 export function Providers({
   children,
   user, // resolved server-side from YOUR auth
 }: {
   children: React.ReactNode;
-  user: { id: string; teamIds: string[] };
+  user: { id: string };
 }) {
   return (
-    <AbloProvider
-      schema={schema}
-      userId={user.id}
-      teamIds={user.teamIds}
-      fallback={<AppSkeleton />}
-    >
+    <AbloProvider client={ablo} userId={user.id} fallback={<AppSkeleton />}>
       {children}
     </AbloProvider>
   );
 }
 ```
 
-`schema` is the only required prop. The rest are situational:
-
-| Prop                | Default                | Purpose                                                                                                   |
-| ------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
-| `schema`            | —                      | **Required.** From `defineSchema()`. Determines the typed hook surface.                                   |
-| `userId`            | resolved from auth     | App participant id for app-owned fields and your `identityRoles.extract`. Not the security boundary.      |
-| `teamIds`           | resolved from auth     | Team ids expanded into team sync groups via `identityRoles`.                                               |
-| `syncGroups`        | full allowed set       | **Narrows** the subscription to a subset of what auth allows (e.g. `['deck:abc123']`). Never widens it.   |
-| `url`               | hosted endpoint        | WebSocket URL of the sync server (`wss://…`). Hosted apps omit it.                                         |
-| `apiKey`            | session/cookie         | Bootstrap auth. Browser apps **omit this** — the key stays server-side. See Identity below.               |
-| `fallback`          | neutral spinner        | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
-| `bootstrapMode`     | `'full'`               | `'full'` loads existing rows before the app renders, so reads are populated on first paint; `'none'` skips that initial load and only streams changes as they happen.|
-| `persistence`       | `'volatile'`           | `'indexeddb'` opts into a durable browser cache that survives reloads.                                     |
-| `onSessionExpired`  | —                      | Fired after the engine has already purged on a rejected session — use for redirect-to-sign-in.            |
-| `onError`           | —                      | Engine / WebSocket / `postBootstrap` errors. Wire to Sentry / Datadog.                                    |
-
-Where `userId` / `teamIds` / `syncGroups` come from, and why the API key never
-reaches the browser, is the whole of
-[Identity & Sync Groups](./identity.md) — read that if it isn't obvious how org
-/ team / user map to what a participant can see.
+`client` is the only required prop. The rest are situational:
+
+| Prop        | Default          | Purpose                                                                                                   |
+| ----------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `client`    | —                | **Required.** The `Ablo({ schema, authEndpoint })` instance. It carries the schema and connection config. |
+| `userId`    | resolved from auth | App participant id for app-owned fields and your `identityRoles`. Not the security boundary.            |
+| `fallback`  | neutral spinner  | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
+| `onError`   | —                | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
+
+Everything that used to be a provider prop — `schema`, `url`, `apiKey`,
+`teamIds`, `syncGroups`/`scope`, `persistence`, `bootstrapMode` — now lives on
+the `Ablo({ ... })` client you build before mounting the provider. Where the
+identity comes from, and why the API key never reaches the browser, is the whole
+of [Identity & Sync Groups](./identity.md) — read that if it isn't obvious how
+org / team / user map to what a participant can see.
 
 ## useAblo — model client
 

package/llms.txt

@@ -6,6 +6,12 @@ Here is the problem it solves. Two writers touch `report_stockholm` at once. The
 
 Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist, coordinate with concurrent work, and leave an audit trail.
 
+## Start here
+
+First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla> --storage datasource`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. It scaffolds `ablo/schema.ts`, the client, the Data Source endpoint, and (for Next.js) the browser provider + session route, all on the current API. Edit the generated files rather than hand-writing from this doc.
+
+Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. After you create or change `ablo/schema.ts`, run `npx ablo push` (one-shot). Until you push, EVERY write to a new or changed model fails with `server_execute_unknown_model`. (Or keep `npx ablo dev` running — it pushes on save.)
+
 ## Use this API
 
 ```ts
@@ -23,15 +29,16 @@ const schema = defineSchema({
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
-const report = await ablo.weatherReports.retrieve('report_stockholm');
+const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
 if (!report) throw new Error('Row not found');
 
-const updated = await ablo.weatherReports.claim('report_stockholm', async (report) => {
-  return ablo.weatherReports.update(
-    report.id,
-    { status: 'ready', forecast: await getForecast(report) },
-    { wait: 'confirmed' },
-  );
+// Claim the row (waits if someone else holds it), read the fresh copy off
+// `claim.data`, write, then auto-release at the end of this scope (`await using`).
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const updated = await ablo.weatherReports.update({
+  id: claim.data.id,
+  data: { status: 'ready', forecast: await getForecast(claim.data) },
+  wait: 'confirmed',
 });
 ```
 
@@ -46,7 +53,7 @@ For full integrations, use `integration-guide` as the canonical doc. It covers
 the same model API across Ablo-managed state, Data Source-backed app databases,
 React selectors, multiplayer, and future agent workers.
 
-Reads come in two flavors, and you pick by whether you can wait. `retrieve(id)`
+Reads come in two flavors, and you pick by whether you can wait. `retrieve({ id })`
 (one row) and `list({ where })` (many) are async — they hit the server and return
 a Promise, so await them. `get(id)`, `getAll({ where })`, and `getCount({ where })`
 are synchronous — they read the local graph and are reactive in render, so no
@@ -68,7 +75,7 @@ first integration path.
 Multiplayer is not a separate mode. When human UI, server actions, and agents use
 the same schema client and write through `ablo.<model>`, Ablo coordinates the
 shared model stream: confirmed deltas fan out to subscribers, active claims are
-visible through `claim.state(id)`, and stale writes can be rejected with `readAt`.
+visible through `claim.state({ id })`, and stale writes can be rejected with `readAt`.
 
 If an app writes directly to its own database outside Ablo, that write bypasses
 coordination until the app reports it through Data Source events.
@@ -76,7 +83,7 @@ coordination until the app reports it through Data Source events.
 ## Nouns
 
 - `Model client` is the typed `ablo.<model>` object generated from schema.
-- `Claim` holds a model row while slow work runs; `claim.state(id)` observes it.
+- `Claim` holds a model row while slow work runs; `claim.state({ id })` observes it.
 - `Commit` is the durable protocol write behind `ablo.<model>.update(...)`.
 - `Receipt` confirms the commit.
 
@@ -121,7 +128,7 @@ import { prisma } from '@/lib/prisma';
 export const { POST } = dataSourceNext({
   schema,
   apiKey: process.env.ABLO_API_KEY!,
-  adapter: prismaDataSource(prisma, schema), // or drizzleDataSource(db, tables)
+  adapter: prismaDataSource(prisma, schema), // or drizzleDataSource(db, schema)
 });
 ```