@abloatai/ablo 0.7.0 → 0.8.0

package/docs/identity.md

@@ -30,65 +30,16 @@ A **sync group** is a named channel of shared state — a string like
 There is no built-in `org` / `team` / `user` concept in the engine. Those are
 *your* domain words. Ablo only knows sync-group strings. The mapping from "this
 is user U in org O" to "they may subscribe to `org:acme` and `user:U`" is
-something **you declare in your schema** — covered next.
-
-### Two kinds of group — the whole mental model
-
-Every sync group is named after one of two things, and that's the cleanest way
-to hold the model in your head:
-
-- **Membership groups** — named after *who you are*: `org:{id}`, `team:{id}`,
-  `user:{id}`. Produced from **identity** (`identityRoles`, Half 1). They're
-  standing and durable — they don't change as you work.
-- **Entity groups** — named after *a thing*: `dataroom:{id}`, `deck:{id}`,
-  `slide:{id}`. Produced from a **row's id** (a model's entity scope, Half 2).
-  They're granular — one per record — and any participant can be pointed at a
-  specific set of them.
-
-Humans and agents fill that same space differently — and, crucially, the two
-are **declared in different places**, because membership is static (a property of
-identity) while entity scope is dynamic (a property of the task):
-
-| | Subscribed by | Declared where | Gets |
-| --- | --- | --- | --- |
-| **Human** | *who they are* — membership | **the schema** (`identityRoles`) — a rule, written once | every `org` / `team` / `user` group their identity implies — their whole standing world |
-| **Agent** | *what it's been given* — entities | **code, at the spawn site** — chosen per run | a handful of entity groups: the dataroom it's in, the slides it has read — never beyond what its user's membership could reach |
-
-> **One line:** humans subscribe by who they are; agents subscribe by what
-> they've been given.
-
-The asymmetry is the point. A user's org/team/user don't change per request, so
-their scope is a **rule the schema derives automatically** — you never write
-per-user scope code. 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
-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
-scope is fully schema-derived.)
-
-So an agent doesn't need a `user:{id}` standing grant. It's a participant pointed
-at a few entity groups, bounded above by its triggering user's membership. That
-boundary is the whole safety story, and it's covered in
-[Agents are participants too](#agents-are-participants-too).
-
-```txt
-your auth → identity { kind, userId|agentId, organizationId, teamIds }
-          → identityRoles (schema) → allowed sync groups
-          → participant receives deltas for rows in those groups
-```
-
-The identity is a **participant** — and a participant is either a human
-(`kind: 'user'`) or an agent (`kind: 'agent'`). Same shape, same path; see
-[Agents are participants too](#agents-are-participants-too) below. Everything in
-the next two sections applies to both.
+something **you declare in your schema**. Here is that whole declaration in one
+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 `syncGroups` prop (narrowing). Here they are in one runnable place — the
-sections after this explain each.
+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.
 
 ```ts
 // 1. src/ablo/schema.ts — map identity → groups, and anchor each model to a group
@@ -144,6 +95,60 @@ export const schema = defineSchema(
 
 That's the whole surface. The rest of this doc is the *why* behind each line.
 
+## Two kinds of group — the whole mental model
+
+You just saw a human get `org` / `team` groups and an agent get one `deck`
+group. That split is the model. Every sync group is named after one of two
+things:
+
+- **Membership groups** — named after *who you are*: `org:{id}`, `team:{id}`,
+  `user:{id}`. Produced from **identity** (`identityRoles`, Half 1). They're
+  standing and durable — they don't change as you work.
+- **Entity groups** — named after *a thing*: `dataroom:{id}`, `deck:{id}`,
+  `slide:{id}`. Produced from a **row's id** (a model's entity scope, Half 2).
+  They're granular — one per record — and any participant can be pointed at a
+  specific set of them.
+
+Humans and agents fill that same space differently, and you declare the two in
+different places. A human's groups come from who they are, so you declare them
+once in the schema. An agent's groups come from what it's working on right now,
+so you pass them in code when you start the run.
+
+| | Subscribed by | Declared where | Gets |
+| --- | --- | --- | --- |
+| **Human** | *who they are* — membership | **the schema** (`identityRoles`) — a rule, written once | every `org` / `team` / `user` group their identity implies — their whole standing world |
+| **Agent** | *what it's been given* — entities | **code, at the spawn site** — chosen per run | a handful of entity groups: the dataroom it's in, the slides it has read — never beyond what its user's membership could reach |
+
+> **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
+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
+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
+scope is fully schema-derived.)
+
+So an agent doesn't need a `user:{id}` standing grant. It's a participant pointed
+at a few entity groups, bounded above by its triggering user's membership. That
+boundary is the whole safety story, and it's covered in
+[Agents are participants too](#agents-are-participants-too).
+
+```txt
+your auth → identity { kind, userId|agentId, organizationId, teamIds }
+          → identityRoles (schema) → allowed sync groups
+          → participant receives deltas for rows in those groups
+```
+
+The identity is a **participant** — and a participant is either a human
+(`kind: 'user'`) or an agent (`kind: 'agent'`). Same shape, same path; see
+[Agents are participants too](#agents-are-participants-too) below. Everything in
+the next two sections applies to both.
+
 ## The two halves of scoping
 
 Scoping is two declarations that meet in the middle. One describes the
@@ -355,9 +360,10 @@ agent authority = (triggering user's allowed set)    ← ceiling, inherited (on-
                 ∩ (the model instances it touches)    ← floor, least privilege per run
 ```
 
-Mechanically, this is the per-model anchor from
-[Half 2](#half-2--per-model-scope-row--group) doing the work. Declare an entity
-anchor on the models an agent operates on:
+Concretely: each model an agent edits declares a `scope`
+([Half 2](#half-2--per-model-scope-row--group)), so each row forms its own
+group. The agent subscribes only to the groups for the rows it touches. Declare
+an entity anchor on the models an agent operates on:
 
 ```ts
 // each scope-root model an agent edits forms a per-entity group
@@ -393,8 +399,8 @@ user it ran on behalf of, so audit answers "who did this, and on whose behalf."
 It never appears in an `identityRole`, because it changes *who's accountable*,
 not *what's reachable*.
 
-This is deliberately the shape the 2025–2026 agent-identity consensus converged
-on, expressed in Ablo's primitives rather than a bolted-on agent ACL:
+Three rules make agent access safe, and they fall out of the model above rather
+than needing a separate agent permission system:
 
 - **Inherit the user, and no more** — the OAuth
   [on-behalf-of](https://workos.com/blog/oauth-on-behalf-of-ai-agents) model: the

package/docs/index.md

@@ -1,37 +1,47 @@
 # Ablo Docs
 
-Ablo is a state control API for **humans and AI agents editing the same
-typed state in real time, with attribution, conflict handling, and
-fast cutoff**.
+You have a database, and you want an AI agent to edit the same rows your
+users are editing — without the two clobbering each other's work. Ablo gives
+the agent a narrow, audited write path: you declare your models, then everyone
+(React components, server actions, and agents) calls the same
+`ablo.deck.update(...)`. Ablo streams confirmed changes to everyone live and
+rejects any write based on stale data.
 
-It gives agents a narrow way to write production state: declare models, load current state, coordinate active work, and write with stale-state checks.
+The flow is four steps: declare your models, read the current rows, claim the
+row you're about to change, then write — and the write is rejected if someone
+changed the row first.
 
-Multiplayer is not a separate product mode. If humans, server actions, and agents
-use the same `Ablo({ schema, apiKey })` client and write through
-`ablo.<model>`, Ablo fans out confirmed deltas, exposes active claims, and
-rejects stale writes for every participant.
+```ts
+// The same call, whether a person, a server action, or an agent makes it.
+await ablo.deck.update(deckId, { title: "Q3 Strategy" });
+```
 
-## What you get, in three commitments
+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.
 
-These commitments drive every design choice in the rest of the docs; if
-they don't match what you're building, the trade-offs land elsewhere
-(Replicache, ElectricSQL, PowerSync for human-only real-time; Zero for
-query-shaped sync).
+## What you get
+
+Three things stay true no matter how you use Ablo:
 
 - **One model API for every actor.** `ablo.<model>.update(...)` is the
   call from React components, server actions, background workers, and
   AI agents alike. No separate "agent SDK," no parallel mutation path.
   Attribution comes from the credential, not the call site.
-- **Server owns the scope convention.** Tenancy / per-entity scope
+- **You declare tenancy scopes once.** Tenancy / per-entity scope
   prefixes (`org:`, `deck:`, or your own `region:` / `customer:`) are
-  declared once on the schema's `identityRoles`. Consumer code never
-  composes group strings. Same boundary Liveblocks (`prepareSession`),
-  PowerSync (named streams), and Zero (synced queries) settled on.
+  declared once on the schema's `identityRoles`, so application code
+  never builds an `org:123` string by hand — which keeps tenant
+  boundaries from leaking.
+- **Stale writes are rejected.** If the row changed after you read it,
+  your write is turned away instead of silently overwriting the change
+  you didn't see.
 
 ## Start here
 
 - [Quickstart](./quickstart.md) — Make your first schema-backed write.
-- [CLI & Migrations](./cli.md) — `init` / `migrate` / `schema push` / `generate`, the shared Zod→Postgres type map, and structured migration errors.
+- [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.
 - [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.
@@ -60,10 +70,11 @@ query-shaped sync).
 
 ## Concepts
 
+- [Schema Contract](./schema-contract.md) — What the schema drives across SDK, React, agents, Data Source, and migrations.
 - [Model Methods](./api.md#model-methods) — Load and write typed state.
 - [Integration Guide](./integration-guide.md) — The normal app path and optional pieces.
 - [Guarantees](./guarantees.md) — Confirmed writes, optimistic state, stale-write protection, and agent lifecycle.
-- [Coordination](./coordination.md) — `claim`, `claimState`, and `queue` for active work.
+- [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue` for active work.
 - [Connect Your Database](./data-sources.md) — Where data lands when your app database is canonical.
 - [Receipt](./api.md#receipt) — Confirm what landed.
 - [Usage](./api.md#usage) — Metering and audit dimensions.

package/docs/integration-guide.md

@@ -1,39 +1,26 @@
 # Integration Guide
 
-Use this guide when you are adding Ablo to a real product, not a demo.
+If humans and AI agents both edit the same records in your app, they overwrite
+each other and there's no good place to coordinate. Ablo gives them one shared,
+typed write path — the same `ablo.<model>.update(...)` call for a React
+component, a server action, a background worker, or an agent — and reconciles the
+edits. This guide adds it to a product that already has a backend and database,
+one model at a time.
 
-## Why Ablo, before the API
-
-Ablo is a sync engine designed from the ground up for **humans and AI
-agents editing the same state at the same time**. That premise drives
-every design choice in this guide; if you only need server-to-server
-data syncing without agents in the loop, the trade-offs land elsewhere
-(Replicache, ElectricSQL, PowerSync are good answers for human-only
-real-time apps; Zero is a good answer for query-shaped sync).
-
-The shape of the SDK reflects three commitments:
+Three things hold no matter which actor is writing:
 
 - **One model API for every actor.** `ablo.<model>.update(...)` is what
   React components, server actions, background workers, and AI agents
   all call. No separate "agent SDK," no parallel mutation path. The
   attribution comes from the credential, not the call site.
-- **Server owns the scope convention; client picks a subset by id.** The
-  `org:` / `user:` / `team:` (or your own `region:` / `customer:`)
-  prefixes live in the schema's `identityRoles` once, never typed by
-  consumer code. Same boundary Liveblocks (`prepareSession`), PowerSync
-  (named streams), and Zero (synced queries) settled on after the same
-  realization: clients that compose scope strings drift; servers that
-  derive scope from authed identity don't.
-- **Capabilities, not API keys, are how agents authenticate.** Static
-  API keys protect server-to-server humans. Agents get per-run,
-  per-scope, leased credentials with per-request signature verification
-  and instant revocation. The 2025-2026 AI-agent auth consensus
-  (OAuth 2.1 / MCP, AWS STS, Vault leases, Auth0 Token Vault) converged
-  on this shape. Capabilities are Ablo's instance.
-
-If you have already built a sync layer or an agent runtime, you know
-what each of those costs. This guide assumes you want them solved once,
-together, behind one client.
+- **You never type `org:123` in client code.** The server derives what each
+  caller can see from their authenticated identity, using the `identityRoles`
+  you declare once in the schema. The client just names which model and id it
+  wants. The `org:` / `user:` / `team:` (or your own `region:` / `customer:`)
+  prefixes live in the schema, never in consumer code.
+- **Agents don't use your account API key.** Each agent run gets a short-lived
+  credential scoped to just what that run can touch, verified per request and
+  revocable instantly. (See the Agents section below for the actual calls.)
 
 ## The integration in one diagram
 
@@ -49,7 +36,7 @@ Declare the models Ablo coordinates, then read and write through
 that same model path.
 
 ```txt
-schema -> ablo.<model>.load(...) -> ablo.<model>.update(...)
+schema -> ablo.<model>.list(...) -> ablo.<model>.update(...)
 ```
 
 Commits and receipts exist under the hood. Most apps do not create protocol
@@ -226,21 +213,28 @@ refreshes before expiry.
 
 ## 3. Read State
 
-Use `load` when the row may not already be local.
+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.
+
+Use `retrieve` when the row may not be local yet — it fetches from the server
+and waits.
 
 ```ts
 await ablo.ready();
 
-const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+const report = await ablo.weatherReports.retrieve('report_stockholm');
 if (!report) throw new Error('report not found');
 ```
 
-Use `retrieve`, `list`, and `count` for synchronous reads after data has
-loaded.
+Use `get`, `getAll`, and `getCount` for synchronous local-graph reads after
+data has synced.
 
 ```ts
-const report = ablo.weatherReports.retrieve('report_stockholm');
-const activeReports = ablo.weatherReports.list({
+const report = ablo.weatherReports.get('report_stockholm');
+const activeReports = ablo.weatherReports.getAll({
   where: { projectId: 'proj_123' },
   filter: (report) => report.status !== 'ready',
   orderBy: { updatedAt: 'desc' },
@@ -260,8 +254,8 @@ export function ReportRow({
 }: {
   report: { id: string; location: string; status: string };
 }) {
-  const report = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claim.state(serverReport.id));
 
   return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
 }
@@ -342,11 +336,11 @@ The migration can be gradual:
 
 1. Declare schema for one model, such as `reports`.
 2. Keep existing server loads for first paint.
-3. Add `useAblo((ablo) => ablo.weatherReports.retrieve(id)) ?? serverReport` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.get(id)) ?? serverReport` for live rows.
 4. Add one Data Source endpoint that calls the existing service layer.
 5. Move one mutation button from `fetch('/api/reports/...')` to `ablo.weatherReports.update(...)`.
 6. Add an outbox/events path for writes that still happen outside Ablo.
-7. Let agents use the same `ablo.weatherReports.load(...)` and `ablo.weatherReports.update(...)`.
+7. Let agents use the same `ablo.weatherReports.list(...)` and `ablo.weatherReports.update(...)`.
 
 For the full Python shape, see
 [Existing Python Backend](./examples/existing-python-backend.md).
@@ -407,8 +401,13 @@ The API key verifies Ablo's request. It is not a database credential.
 Agents should use the same model methods as the app when they can import the
 schema.
 
+An agent often reads a row, calls an LLM, then writes back — a slow gap during
+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.load({ where: { id: reportId } });
+const report = await ablo.weatherReports.retrieve(reportId);
 if (!report) return;
 
 await ablo.weatherReports.claim(
@@ -455,7 +454,7 @@ Keep agent writes on the same schema client surface as the app.
 | `/testing`                                | Test harnesses and deterministic mocks.                           |
 | `Data Source`                             | Keep your app database canonical.                                 |
 | `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
-| `claim` / `claimState` / `queue`          | Show active work and coordinate before a write.                   |
+| `claim` / `claim.state` / `claim.queue`          | Show active work and coordinate before a write.                   |
 | `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
 | `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
@@ -465,16 +464,17 @@ them.
 
 ## Method Cheatsheet
 
-| Method                       | Use it for                                                       |
-| ---------------------------- | ---------------------------------------------------------------- |
-| `load({ where })`            | Async hydration from backing store/server.                       |
-| `retrieve(id)`               | Synchronous read of one already-loaded row.                      |
-| `list(options?)`             | Synchronous collection read of loaded rows.                      |
-| `count(options?)`            | Synchronous count of loaded 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.                                  |
-| `claimState(id)`             | See active work on a model row.                                  |
-| `claim(id, work, options?)`  | Wait for your turn, re-read, and hold the row while `work` runs. |
+| 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.

package/docs/interaction-model.md

@@ -1,28 +1,40 @@
 # Interaction Model
 
-Ablo's public model is the path every human UI, server action, and agent uses on
-every write:
+When a person, a server action, and an AI agent can all write to the same row,
+you need one write path that stops them from clobbering each other. Ablo gives
+you exactly one: load the row, claim it while you work, update it, and wait for
+confirmation. This page walks through that path and the few primitives behind it.
 
-```
-Schema -> Model load -> Claim -> Model update -> Confirmation
+Here's the whole path in one block — claim a row, update it inside the claim, and
+let the claim release when your callback returns:
+
+```ts
+const report = await ablo.weatherReports.retrieve('report_stockholm');
+
+await ablo.weatherReports.claim('report_stockholm', async (report) => {
+  await ablo.weatherReports.update(report.id, { status: 'ready' }, { wait: 'confirmed' });
+});
 ```
 
+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.
+
 ## Primitives
 
 | Primitive | Plane | Purpose |
 |---|---|---|
 | `Schema` | State | Declares typed models the app and agents can read and write. |
-| `Model` | State | The generated `ablo.<model>` model. Use `load`, `retrieve`, `create`, `update`, and `delete`. |
-| `Claim` | Coordination | Who is working on a target. Claimed via `ablo.<model>.claim(id, ...)` and read via `ablo.<model>.claimState(id)`. Ephemeral — never persisted. |
+| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async server reads), `get`/`getAll`/`getCount` (synchronous local reads), `create`, `update`, and `delete`. |
+| `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim(id, work)` and read via `ablo.<model>.claim.state(id)`. Ephemeral — never persisted. |
 | `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
 | `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
 
 ### Why each primitive is separate
 
-The plane separation isn't ceremony — collapsing any two of these would
-lose a property that's hard to recover later. A reader coming from
-Replicache or Yjs would expect just `Commit`; here's what the others buy
-you over that minimum:
+Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
+does a job the others can't. If you're coming from Replicache or Yjs you'd
+expect just `Commit`; here's what the other two buy you over that minimum:
 
 - **`Claim` is not a read lock.** Reads stay open. Claims serialize
   acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
@@ -33,45 +45,45 @@ you over that minimum:
   client. A status code can't be re-read by a sub-agent that wasn't on
   the original call.
 
-The shape is borrowed from systems that learned the cost of collapse:
-coordination from operational-transform CRDTs and Linear's optimistic
-multiplayer model, and receipts from durable write protocols.
-
 ## Run Loop
 
 A normal schema-backed run is:
 
-```
-const [report] = await ablo.weatherReports.load({ where: { id } });
-const active = ablo.weatherReports.claimState(id);
+```ts
+const report = await ablo.weatherReports.retrieve(id);
+const active = ablo.weatherReports.claim.state(id);
 await ablo.weatherReports.claim(id, async (report) => {
   await ablo.weatherReports.update(report.id, patch, { wait: 'confirmed' });
 });
 ```
 
+`retrieve(id)` is an async server read (await it). `claim.state(id)` is a
+synchronous local read of who currently holds the row — it never blocks.
+
 ## Coordination
 
 > Loop view only. Full claim reference — methods, the claim-state object, the
-> `queue`, errors — is [Coordination](./coordination.md).
+> `claim.queue`, errors — is [Coordination](./coordination.md).
 
-Claims broadcast across the org. Claim a row through the flat model verb, write
-through the normal `update`, and the claim releases when the callback returns:
+Claims broadcast across the org. Call `claim(id, callback)`, do your writes with
+the normal `update` inside the callback, and the claim releases automatically
+when the callback returns:
 
 ```ts
 await ablo.weatherReports.claim(
   'report_stockholm',
   async (report) => {
-    await ablo.weatherReports.update(report.id, { status: 'ready' }); // stale-guarded under the claim
+    await ablo.weatherReports.update(report.id, { status: 'ready' }); // rejected if the row changed under the claim
   },
   { action: 'editing' },
 );
 ```
 
-`ablo.weatherReports.claimState('report_stockholm')` reads the live claim (or `null`) without
-blocking. The claim is **advisory**: if another participant holds the row,
-`claim` waits for them to finish and re-reads before handing back the row. The
-same signal is visible to every schema client through `claimState(id)` and the live
-claim stream.
+`ablo.weatherReports.claim.state('report_stockholm')` reads the live claim (or
+`null`) without blocking. Claims don't lock: if another participant holds the
+row, `claim` waits for them to finish, re-reads, and then hands you the fresh
+row. The same signal is visible to every schema client through `claim.state(id)`
+and the live claim stream.
 
 ## Conflict resolution
 

package/docs/mcp/claude-code.md

@@ -6,19 +6,9 @@
 claude mcp add --transport http ablo-sync https://<your-app>/api/mcp
 ```
 
-That's it. The next `/help` in Claude Code will list the Ablo Sync tools.
-
-## With auth
-
-If your deployment requires a scoped bearer token (production setups should):
-
-```bash
-claude mcp add --transport http ablo-sync https://<your-app>/api/mcp \
-  --header "Authorization=Bearer $ABLO_MCP_TOKEN"
-```
-
-Create a session-scoped bearer token from your server or dashboard — see
-[MCP overview](/docs/mcp#auth).
+That's it — no token or header needed. The endpoint is public and serves
+only docs, schema lint, and scaffolds. The next `/help` in Claude Code will
+list the Ablo Sync tools.
 
 ## Verify
 
@@ -28,7 +18,9 @@ In Claude Code, run:
 /mcp list
 ```
 
-You should see `ablo-sync` with the model tools enumerated.
+You should see `ablo-sync` with the integration tools enumerated:
+`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`,
+`scaffold_app`.
 
 ## Removing
 
@@ -38,6 +30,6 @@ claude mcp remove ablo-sync
 
 ## More
 
-- [MCP overview](/docs/mcp) — how the transport works.
-- [Cursor setup](/docs/mcp/cursor) — same JSON, different UI.
-- [Windsurf setup](/docs/mcp/windsurf) — same JSON, different UI.
+- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
+- [Cursor setup](/docs/mcp/cursor) — same URL, different UI.
+- [Windsurf setup](/docs/mcp/windsurf) — same URL, different UI.

package/docs/mcp/cursor.md

@@ -15,39 +15,21 @@ Add the Ablo Sync MCP server to Cursor's `mcp.json`:
 }
 ```
 
-The file lives at `~/.cursor/mcp.json` on macOS / Linux.
+The file lives at `~/.cursor/mcp.json` on macOS / Linux. No auth header is
+needed — the endpoint is public and serves only docs, schema lint, and
+scaffolds.
 
 Restart Cursor. The Ablo Sync tools appear under the MCP icon in the agent
 panel.
 
-## With auth
-
-Add a `headers` block:
-
-```json
-{
-  "mcpServers": {
-    "ablo-sync": {
-      "transport": "http",
-      "url": "https://<your-app>/api/mcp",
-      "headers": {
-        "Authorization": "Bearer $ABLO_MCP_TOKEN"
-      }
-    }
-  }
-}
-```
-
-Cursor expands shell-style env vars in this block. Set `ABLO_MCP_TOKEN`
-in your shell config.
-
 ## Verify
 
 In Cursor's agent panel, open the MCP tools list. You should see the
-Ablo Sync model tools and their JSON schemas.
+Ablo Sync integration tools and their JSON schemas: `search_ablo_docs`,
+`get_recipe`, `get_api_surface`, `validate_schema`, `scaffold_app`.
 
 ## More
 
-- [MCP overview](/docs/mcp) — how the transport works.
+- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
 - [Claude Code setup](/docs/mcp/claude-code) — CLI install.
 - [Windsurf setup](/docs/mcp/windsurf) — same JSON shape.