@abloatai/ablo 0.11.0 → 0.11.2

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

package/docs/integration-guide.md

@@ -44,13 +44,18 @@ objects by hand.
 
 ## Your Database
 
-Every schema model is backed by **your own database**. You expose a signed Data
-Source endpoint; Ablo coordinates each write and your app commits it to your
-Postgres. The SDK call shape is the same everywhere.
+Every schema model is backed by **your own database**. The SDK call shape is the
+same everywhere.
 
-Do not pass a database URL to `Ablo(...)`. Application and agent code use
-`ABLO_API_KEY`. If your database stays canonical, expose a signed Data Source
-endpoint from your app and keep the database credentials inside your app.
+In this guide — an app that already owns its backend and database — keep
+`DATABASE_URL` inside your app and expose a signed Data Source endpoint: Ablo
+coordinates each write and your app commits it to your Postgres. Do not pass
+`databaseUrl` to `Ablo(...)` here; application and agent code use `ABLO_API_KEY`.
+
+If instead you want Ablo to connect to your Postgres directly, pass `databaseUrl`
+(a live, server-only option) to `Ablo(...)`. That and the sandbox-only `apiKey`
+shape are the other two start states — [Connect Your Database](./data-sources.md)
+is the single source of truth for all three.
 
 ## Test With Sandboxes
 
@@ -94,12 +99,13 @@ import { defineSchema, model, z } from '@abloatai/ablo/schema';
 export const schema = defineSchema(
   {
     weatherReports: model({
-      id: z.string(),
+      // Reserved fields (id, createdAt, updatedAt, organizationId, createdBy)
+      // are SDK-provided automatically — never declare them. Declare only your
+      // own fields.
       projectId: z.string(),
       location: z.string(),
       status: z.enum(['pending', 'ready']),
       assigneeId: z.string().nullable(),
-      updatedAt: z.string(),
     }),
   },
   {
@@ -169,7 +175,7 @@ export const ablo = Ablo({
 Browser apps should use the React provider or a scoped session token, not a
 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
+nothing else (`schema`, `teamIds`, and `apiKey` all live on the
 client now).
 
 ```tsx
@@ -179,7 +185,10 @@ 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' });
+export const ablo = Ablo({
+  schema,
+  apiKey: () => fetch('/api/ablo-session').then((r) => r.text()),
+});
 ```
 
 ```tsx

package/docs/migration.md

@@ -11,6 +11,7 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
+| **0.11.0** | `intent` → `claim` rename completed across the React hook, type namespace, and wire frames | `useIntent` → `useClaim`; `Register.Intents` → `Register.Claims`; `Ablo.Intent.*` → `Ablo.Claim.*`. Upgrade client **and** server together (wire frames moved `intent_*` → `claim_*`) |
 | **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Update code that branches on the environment (e.g. source `mode`): `'test'`→`'sandbox'`, `'live'`→`'production'`. Key prefixes `sk_test_`/`sk_live_` are unchanged |
 | **0.9.2** | `turn` primitive + agent-work `tasks` resource removed | Coordinate with `claim`; mint a scoped session instead of `agent().run()` |
 | **0.9.2** | `intents` deprecated in favor of `claim` | Use `ablo.<model>.claim`; `ablo.intents` is now `@internal` |
@@ -24,6 +25,45 @@ change when you upgrade.
 
 ---
 
+## 0.11.0 — `intent` → `claim` rename completed
+
+The coordination primitive has been `claim` since 0.9.2, but a few `intent`-named
+surfaces lingered. 0.11.0 finishes the rename. There are three edits, all
+mechanical:
+
+**1. React hook.** `useIntent` is now `useClaim` (same signature):
+
+```diff
+- import { useIntent } from '@abloatai/ablo/react';
+- const claimEditLayer = useIntent('editLayer');
++ import { useClaim } from '@abloatai/ablo/react';
++ const claimEditLayer = useClaim('editLayer');
+```
+
+**2. Type registration.** The `Register` interface key is `Claims`, not `Intents`:
+
+```diff
+  declare module '@abloatai/ablo' {
+    interface Register {
+-     Intents: { editLayer: { slideId: string; layerId: string } };
++     Claims: { editLayer: { slideId: string; layerId: string } };
+    }
+  }
+```
+
+**3. Type namespace.** The `Ablo.Intent.*` helper types moved to `Ablo.Claim.*`.
+If you referenced them directly, rename the namespace; the shapes are unchanged.
+
+> **Coordinated deploy required.** The on-the-wire frames moved from `intent_*`
+> to `claim_*`. A `claim_*`-aware client cannot coordinate with an `intent_*`
+> server (and vice-versa), so ship the client and server together. If you run a
+> self-managed sync server, deploy it first.
+
+Two non-breaking improvements ride along: claim-rejection errors now surface the
+contending holders (`AbloClaimedError.claims` and a policy reason folded into the
+message), and `participantKind` is the canonical `'user' | 'agent' | 'system'`
+on presence and claim state.
+
 ## 0.10.0 — environment enum `sandbox` / `production`; stateless HTTP transport
 
 ### Environment enum rename (the only breaking change)
@@ -73,6 +113,11 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http'
 await ablo.tasks.update({ id, data: { status: 'done' } });
 ```
 
+> **Minting still needs the stateful client.** `sessions.create(...)` is not on
+> the `transport: 'http'` surface. Keep a default-transport `server` client for
+> minting short-lived credentials (see the 0.9.2 example below), and use the
+> http client for the per-request reads and writes.
+
 ---
 
 ## 0.9.2 — `turn` / agent-`tasks` removed; `intents` deprecated
@@ -95,8 +140,10 @@ helper, and the agent/task type family (`Agent`, `AgentOptions`,
 ```diff
 - const turn = await engine.beginTurn();
 - await Ablo({ apiKey }).agent(agentId, opts).run(prompt, handler);
-+ // Mint a scoped credential, then claim + write under it.
-+ const { token } = await ablo.sessions.create({ agent: { id: agentId } });
++ // Mint a scoped credential from a stateful (default-transport) server client —
++ // sessions.create lives on the stateful client, not on transport: 'http'.
++ const server = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
++ const { token } = await server.sessions.create({ agent: { id: agentId } });
 + const agent = Ablo({ schema, apiKey: token });
 + await using claim = await agent.tasks.claim({ id });
 + await agent.tasks.update({ id, data: { status: 'done' }, wait: 'confirmed' });

package/docs/quickstart.md

@@ -1,11 +1,16 @@
 # Quickstart
 
-Build with Ablo on **your own database**. You declare a small Ablo schema for the
-models humans and agents edit together, hand the client your Postgres
-`DATABASE_URL`, and coordinate every write through `ablo.<model>`. Your database
-is the system of record — Ablo never hosts your data. It is the transaction
-layer on top: it registers your connection, commits every write there behind
-row-level security, and fans the confirmed rows out to every connected client.
+Build with Ablo on **the Postgres you already have**. You declare a small Ablo
+schema for the models humans and agents edit together, hand the client your
+Postgres `DATABASE_URL` (passed explicitly), and coordinate every write through
+`ablo.<model>`. In production, your database is the system of record. Ablo is the
+transaction layer on top: it registers your connection, commits every write there
+behind row-level security, and fans the confirmed rows out to every connected
+client.
+
+> No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
+> pass an `apiKey` only and omit `databaseUrl`, like Stripe test mode — so you can
+> try Ablo before pointing it at your Postgres.
 
 ## 1. Install and initialize
 
@@ -25,10 +30,12 @@ instead:
 export ABLO_API_KEY=sk_test_...
 ```
 
-Every SDK and CLI call needs a key. Test and live keys work like Stripe's —
-except both point at databases *you* own: `sk_test_*` for your dev database,
-`sk_live_*` for production. There is no keyless mode; the public `/sandbox` page
-is a hosted demo, not your app.
+Every SDK and CLI call needs a key. Test and live keys work like Stripe's:
+`sk_test_*` for the sandbox, `sk_live_*` for production. In production a key
+points at the database *you* own; in the sandbox you can skip the database
+entirely and let Ablo's test plane host the rows (apiKey only). There is no
+keyless mode — a key is always required. (The public `/sandbox` page is a
+separate hosted demo, not your app.)
 
 ## 2. Your Ablo schema (init scaffolded it)
 
@@ -50,19 +57,28 @@ export const schema = defineSchema({
 });
 ```
 
+**Reserved fields** — `id`, `createdAt`, `updatedAt`, `organizationId`, and
+`createdBy` are provided by the SDK automatically. Don't declare them in your
+`model(...)` fields; declare only your own.
 
-Register the schema once (init scaffolds this `ablo.d.ts`), and every type
-is one parameter away — no `typeof schema` re-stating, anywhere:
+The schema is registered once (init scaffolds `ablo/register.ts` for you), and
+every type is one parameter away — no `typeof schema` re-stating, anywhere:
 
 ```ts
-// ablo.d.ts — once per project
-import type { schema } from './ablo/schema';
+// ablo/register.ts — scaffolded by `npx ablo init`, sits beside ablo/schema.ts
+import type { schema } from './schema';
 declare module '@abloatai/ablo' {
   interface Register { Schema: typeof schema }
 }
 export {};
 ```
 
+It's a regular `.ts` module, not a hand-authored `.d.ts`. The top-level
+`import type { schema }` makes the `declare module` block *merge* into (augment)
+the SDK's `Register` interface instead of colliding with it — the same shape
+[TanStack Router uses in `src/router.tsx`](https://tanstack.com/router/latest/docs/framework/react/guide/type-safety). Any `.ts` file in your
+`tsconfig` `include` works; it never needs to be imported.
+
 ```ts
 import type { Model } from '@abloatai/ablo/schema';
 
@@ -73,6 +89,12 @@ type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
 TanStack-Router pattern: declare the source of truth once, everything
 infers from it.)
 
+When you need to name the client type — to pass it to a function or store it in
+a context — **infer it from the value**: `type Sync = typeof sync`. That's the
+same idiom as tRPC's `typeof appRouter` and Drizzle's `typeof db`; it resolves
+the typed overload at the call site. Avoid `ReturnType<typeof Ablo>`, which
+collapses to the untyped client.
+
 ## 3. Point Ablo at your database
 
 The client takes your schema, your key, and your `DATABASE_URL`. On first
@@ -93,10 +115,14 @@ import { schema } from './schema';
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
-  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
+  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
 ```
 
+`databaseUrl` is not auto-read from the environment — you pass it explicitly
+(as above). If a `DATABASE_URL` is set for another tool, `Ablo()` ignores it
+unless you wire it in like this.
+
 Use a dedicated **non-superuser role** for the connection — Ablo enforces
 tenant isolation with row-level security, so the server rejects superuser or
 `BYPASSRLS` roles outright (`database_role_cannot_enforce_rls`).
@@ -127,29 +153,34 @@ built from an ORM adapter instead — same product, same writes, see
 [Connect Your Database](./data-sources.md). In that setup, omit `databaseUrl`
 from `Ablo(...)`.
 
-## 4. Push — Ablo provisions your tables for you
+## 4. Push the schema, then map it to tables
 
 ```bash
 npx ablo push      # checks your DATABASE_URL role, pushes the schema (sandbox),
-                   # provisions your synced-model tables (with row-level
-                   # security) IN YOUR database, and writes ABLO_API_KEY to
-                   # .env.local. Add --watch to re-push on every save.
+                   # and writes ABLO_API_KEY to .env.local. Add --watch to
+                   # re-push on every save.
 ```
 
-Nothing runs locally — there is no dev server to start. Your app talks to
-Ablo's hosted API with the sandbox key; the rows land in your database.
+`ablo push` uploads the schema *definition* — model names, fields, types. That
+metadata is what tells Ablo which models to coordinate. Skipping it makes every
+write to a new or changed model fail with `server_execute_unknown_model` — that
+error literally means "run `npx ablo push`."
+
+Now Ablo needs real Postgres tables behind those models. Two ways, depending on
+who owns the tables:
 
-There is no separate migration step: the push provisions your synced-model
-tables in the registered database server-side — your other tables are left
-untouched. (`npx ablo migrate` still exists for the signed Data Source
-endpoint mode, where Ablo never touches your database and DDL must run from
-your side.)
+- **Adopt existing tables (the common case).** Most teams already have the
+  tables — created by Prisma, Drizzle, or hand-written migrations. Run
+  `npx ablo pull` to import their shape into your schema, or `npx ablo check`
+  to verify your schema and the live tables agree. Keep managing the tables
+  with your own migration tool; Ablo just syncs the subset of models you
+  declared.
+- **Let Ablo provision them.** If Ablo should own the tables, `npx ablo migrate`
+  creates your synced-model tables (with row-level security) in the registered
+  database. Your other tables are left untouched.
 
-`ablo push` uploads the schema *definition* —
-model names, fields, types. That metadata is the only thing Ablo keeps; the
-rows stay in your database. Skipping the push makes every write to a new or
-changed model fail with `server_execute_unknown_model` — that error literally
-means "run `npx ablo push`."
+Nothing runs locally — there is no dev server to start. Your app talks to Ablo's
+hosted API with the sandbox key; the rows land in your database.
 
 ## 5. Write through the model
 
@@ -182,8 +213,9 @@ and you write the usual way with `ablo.<model>.update({ id, data })`.
 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. Normal reads still work while the claim is held. If a server read
-should not return a row while someone else is mid-edit, pass `ifClaimed: 'wait'`
-to wait for the claim to clear, or `ifClaimed: 'fail'` to error out instead.
+should not return a row while someone else is mid-edit, 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).
 Call `handle.release()` when your work is done.
 
 ```ts