@abloatai/ablo 0.6.0 → 0.7.0

package/docs/identity.md

@@ -62,7 +62,7 @@ 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* (`entity: 'deck'` → `deck:{id}`);
+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.)
@@ -85,35 +85,38 @@ the next two sections applies to both.
 
 ## Declare it, end to end
 
-The entire declaration surface is three things: `identityRoles` (who may see
-what), `syncGroupFormat` (which group a row fans out on), and an optional
-`syncGroups` prop (narrowing). Here they are in one runnable place — the sections
-after this explain each.
+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.
 
 ```ts
-// 1. src/ablo.schema.ts — map identity → groups, and anchor each model to a group
-import { defineSchema, identityRole, model, z } from '@abloatai/ablo/schema';
+// 1. src/ablo/schema.ts — map identity → groups, and anchor each model to a group
+import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
   {
-    conversations: model(
-      { title: z.string(), createdBy: z.string() },
-      {},
-      { orgScoped: true, syncGroupFormat: 'conversation:{id}' },
-    ),
+    // A scope root: its rows form the group `deck:<id>` (kind from `scope`).
     decks: model(
       { title: z.string(), status: z.enum(['draft', 'published']) },
       {},
-      { orgScoped: true, syncGroupFormat: 'deck:{id}' },
+      { orgScoped: true, scope: 'deck' },
+    ),
+    // A child: it has no group of its own; it inherits its deck's group via the
+    // `parent` edge. A write to a slide reaches everyone viewing the deck.
+    slides: model(
+      { deckId: z.string() },
+      { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
+      { orgScoped: true },
     ),
   },
   {
-    // Each role is pure data: a `template` and the identity `source` field to
-    // read. No closures — so the schema stays JSON-serializable end to end.
+    // Each role is pure data: a `kind` (the group prefix) and the identity
+    // `source` field to read. No closures — so the schema stays JSON-serializable.
     identityRoles: [
-      identityRole({ kind: 'tenant', template: 'org:{id}', source: 'organizationId' }),
-      identityRole({ kind: 'participant', template: 'user:{id}', source: 'userId' }),
-      identityRole({ kind: 'membership', template: 'team:{id}', source: 'teamIds', multi: true }),
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
+      identityRole({ kind: 'team', source: 'teamIds', multi: true }),
     ],
   },
 );
@@ -127,11 +130,13 @@ export const schema = defineSchema(
 ```
 
 ```tsx
-// 3. an AGENT run inherits its user, narrowed to the entities in play
+// 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
-  syncGroups={[`conversation:${conversationId}`, `deck:${deckId}`]} // floor: just its work
+  userId={user.id}                // ceiling: the triggering user
+  scope={{ decks: deckId }}       // floor: just the deck it's working on
 >
   {children}
 </AbloProvider>
@@ -148,15 +153,15 @@ row's sync group is in the participant's allowed set.
 
 ### Half 1 — `identityRoles`: identity → allowed groups
 
-Declared once, on the schema, via the `identityRole({ kind, template, source })`
-factory. Each role is **pure data**: a `template` with a single `{id}`
-placeholder, and the `source` — the identity field to read. The engine reads
-`source` off the identity *you* supply and substitutes each value into the
-`template` to build the participant's allowed set. There is no hardcoded `org:` /
-`user:` anywhere in the engine — the templates and sources are entirely yours.
+Declared once, on the schema, via the `identityRole({ kind, source })` factory.
+Each role is **pure data**: a `kind` (the group's prefix — `org`, `user`, `team`)
+and the `source` — the identity field to read. The engine reads `source` off the
+identity *you* supply and mints `<kind>:<value>` for each value, building the
+participant's allowed set. There is no hardcoded `org:` / `user:` anywhere in the
+engine — the kinds and sources are entirely yours.
 
 ```ts
-// src/ablo.schema.ts
+// src/ablo/schema.ts
 import { defineSchema, identityRole, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
@@ -168,10 +173,10 @@ export const schema = defineSchema(
   },
   {
     identityRoles: [
-      identityRole({ kind: 'tenant', template: 'org:{id}', source: 'organizationId' }),
-      identityRole({ kind: 'participant', template: 'user:{id}', source: 'userId' }),
-      // `multi: true` reads an array field — one team group per id.
-      identityRole({ kind: 'membership', template: 'team:{id}', source: 'teamIds', multi: true }),
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
+      // `multi: true` reads an array field — one `team:<id>` group per id.
+      identityRole({ kind: 'team', source: 'teamIds', multi: true }),
     ],
   },
 );
@@ -189,27 +194,66 @@ in-process and on a hosted server that only ever sees the compiled JSON.
 
 ### Half 2 — per-model scope: row → group
 
-On each model's options, you declare how its rows are tenanted and which
-sync-group label they fan out on.
+You never write a sync-group string for a row. You declare a model's *place* in
+the entity graph and the engine derives the groups its rows fan out on. Three
+declarations, in order of how often you reach for them:
+
+**`scope` — this model is a scope root.** Its rows form a group of their own.
+The kind comes from the model's `typename` by default, or pass a string to set
+it explicitly (use the string form when the wire kind differs from the typename,
+e.g. typename `SlideDeck` but group `deck:<id>`):
 
 ```ts
-model(
-  { /* fields */ },
-  { /* relations */ },
+decks: model({ title: z.string() }, {}, { orgScoped: true, scope: 'deck' });
+// a deck row → group `deck:<id>`
+```
+
+**`parent` — this row lives inside another entity.** Mark the `belongsTo` edge
+to its owner; the row inherits that owner's group. This is the Zanzibar/ReBAC
+*parent* relation — "access inherits from parent" — and it chains transitively
+(a layer → its slide → its deck), so a write to any descendant reaches everyone
+viewing the root. A *reference* (a provenance/template pointer, not ownership)
+must **not** be marked `parent`, or the row would leak into an unrelated scope:
+
+```ts
+slides: model(
+  { deckId: z.string(), sourceSlideId: z.string().optional() },
   {
-    // Rows carry organization_id; bootstrap + fan-out filter on it.
-    orgScoped: true,
+    deck: relation.belongsTo('decks', 'deckId', { parent: true }),  // ownership → inherit deck:<id>
+    sourceSlide: relation.belongsTo('slides', 'sourceSlideId'),     // reference → NOT routed
+  },
+  { orgScoped: true },
+);
+```
+
+> **Declare the parent edge — don't infer it.** Optionality is not a proxy for
+> ownership: many `parent` FKs are optional (a root folder, an inbox task), and
+> some required FKs are mere references. Containment is a fact only you know, so
+> it's declared, exactly as it is in OpenFGA/Zanzibar.
 
-    // Per-entity anchor. Lets a session narrow into ONE row's scope,
-    // e.g. open a single deck: syncGroupFormat.replace('{id}', deckId).
-    syncGroupFormat: 'deck:{id}',
+**`grants` — a membership edge.** On a join model (e.g. `dataroomMember`), it
+says "this row grants a *subject* access to a *scope root*." Both are relation
+names on the model. The server resolves it at connect time — for user `U`, it
+finds the scope-root groups `U` is a member of and adds them to `U`'s allowed
+set (Linear's `/sync/user_sync_groups`). Use this for sub-org sharing; plain
+org membership is already covered by the `org:` identity role.
+
+```ts
+dataroomMember: model(
+  { userId: z.string(), dataroomId: z.string() },
+  {
+    member: relation.belongsTo('users', 'userId'),
+    room: relation.belongsTo('datarooms', 'dataroomId'),
   },
+  { orgScoped: true, grants: { subject: 'member', scope: 'room' } },
 );
 ```
 
-For rows that don't carry `organization_id` directly but inherit tenancy
-through a foreign key, use `scopedVia` rather than `orgScoped: false` — the
-latter exposes the whole table cross-tenant. See
+For the rare group keyed on a plain field rather than a relation (per-recipient
+inbox fan-out, say), there's an `entityRoles: [entityRole({ kind, source })]`
+escape hatch. For rows that inherit *tenancy* (not a sync group) through a
+foreign key without carrying `organization_id`, use `scopedVia` rather than
+`orgScoped: false` — the latter exposes the whole table cross-tenant. See
 `packages/sync-engine/src/schema/model.ts` for the full option set.
 
 ## How identity reaches Ablo — the proxy model
@@ -255,7 +299,7 @@ resolve the user in a Server Component and pass it down:
 ```tsx
 // app/providers.tsx — 'use client'
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 
 export function Providers({
   children,
@@ -316,22 +360,23 @@ Mechanically, this is the per-model anchor from
 anchor on the models an agent operates on:
 
 ```ts
-// a conversation and the deck an agent edits each get a per-entity group
-conversations: model({ /* … */ }, {}, { syncGroupFormat: 'conversation:{id}' }),
-decks:         model({ /* … */ }, {}, { syncGroupFormat: 'deck:{id}' }),
+// each scope-root model an agent edits forms a per-entity group
+documents: model({ /* … */ }, {}, { orgScoped: true, scope: 'document' }),
+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 conversation + one deck
+// 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}
-  // authority narrowed to just the entities in play (the floor)
-  syncGroups={[`conversation:${conversationId}`, `deck:${deckId}`]}
+  // 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 }}
 >
 ```
 
@@ -368,24 +413,50 @@ 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 a single entity
+## Narrowing to specific entities — the `scope` prop
 
-For a page that should only sync one record, combine a per-entity
-`syncGroupFormat` (Half 2) with the `syncGroups` prop:
+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>`.
 
-```ts
-// schema: decks fan out on deck:{id}
-syncGroupFormat: '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
-// page provider: subscribe to just this deck (still inside what auth allows)
-<AbloProvider schema={schema} userId={user.id} syncGroups={[`deck:${deckId}`]}>
+// a page on one deck
+<AbloProvider schema={schema} userId={user.id} scope={{ decks: deckId }} />
+
+// an agent working across two decks and a document
+<AbloProvider
+  schema={schema}
+  userId={user.id}
+  scope={{ decks: [deckA, deckB], documents: docId }}
+/>
 ```
 
-The participant now receives deltas for that one deck instead of the whole org
-— smaller bootstrap, less fan-out — without weakening the server-enforced
-boundary.
+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` prop (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.
 
 ## How this compares — and the best practices it follows
 
@@ -426,13 +497,13 @@ 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` / `syncGroups` props are *untrusted client
+   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.
 
-3. **Scope by a hierarchical naming convention, declared once.** Ablo's
-   `identityRoles` templates (`org:{id}`, `team:{id}`, `deck:{id}`) are the same
-   idea as [Liveblocks' recommended room-id naming pattern](https://liveblocks.io/docs/authentication/access-token)
+3. **Scope by a hierarchical naming convention, declared once.** Ablo's `kind:id`
+   group naming (`org:…` / `team:…` from `identityRoles`, `deck:…` from a model's
+   `scope`) is the same idea as [Liveblocks' recommended room-id naming pattern](https://liveblocks.io/docs/authentication/access-token)
    (`org:*`, `org:group:*`) and [Ably's channel capabilities](https://ably.com/docs/auth/capabilities).
    Declaring the convention in one place — never composing scope strings in
    consumer code — is the practice all three enforce.

package/docs/index.md

@@ -31,6 +31,7 @@ query-shaped sync).
 ## 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.
 - [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.
@@ -38,6 +39,7 @@ query-shaped sync).
 - [API Reference](./api.md) — Model-by-model method shape.
 - [Client Behavior](./client-behavior.md) — Options, errors, retries, timeouts, and imports.
 - [Connect Your Database](./data-sources.md) — Keep canonical rows in your app database without giving Ablo database credentials.
+- [React](./react.md) — Provider, hooks, and reactive reads for React apps.
 - [API Keys](./api-keys.md) — Bearer tokens for the public API.
 
 ## API shape
@@ -65,12 +67,15 @@ query-shaped sync).
 - [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.
+- [Audit Log](./audit.md) — Trace any confirmed write back to the human behind it.
+- [MCP](./mcp.md) — Expose Ablo models to MCP clients (Claude, Cursor).
 
 ## Examples
 
 - [AI SDK Tool](./examples/ai-sdk-tool.md) — Put Ablo inside an AI SDK tool call.
 - [Existing Python Backend](./examples/existing-python-backend.md) — Add multiplayer and future agent writes without replacing a Python API server.
 - [Agent + Human](./examples/agent-human.md) — Yield when a human is editing the same report.
+- [Agent Scoped to One Deck](./examples/scoped-agent.md) — Scope an agent to one entity with `scope` / `parent`; realtime for just that deck.
 - [Server Agent](./examples/server-agent.md) — Schema-backed worker.
 - [Next.js](./examples/nextjs.md) — App-router setup with React bindings.
 
@@ -83,3 +88,4 @@ query-shaped sync).
 - [README](../README.md) — product overview and first example.
 - [AGENTS.md](../AGENTS.md) — short installation guidance for coding assistants.
 - [Changelog](../CHANGELOG.md) — what shipped recently.
+- [Roadmap](./roadmap.md) — what's planned next.

package/docs/integration-guide.md

@@ -101,10 +101,10 @@ wait: 'confirmed' }), and add a smoke test for two concurrent writers.
 
 Start with fields and relations. Keep load strategies, indexing hints, and
 read-only/mutable shortcuts out of the first version unless you already need
-offline-heavy local cache behavior.
+them.
 
 ```ts
-// src/ablo.schema.ts
+// src/ablo/schema.ts
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
@@ -119,23 +119,15 @@ export const schema = defineSchema(
     }),
   },
   {
-    // Identity-anchored sync-group roles. The server walks these to
-    // build each participant's allowed subscription set from the
-    // resolved identity context. Templates and extractors are fully
-    // consumer-controlled — no hardcoded `org:` / `user:` convention
-    // anywhere in the engine. Omit `identityRoles` entirely if your
-    // schema doesn't need identity-derived scoping.
+    // Identity-anchored sync-group roles. The server walks these to build each
+    // participant's allowed subscription set from the resolved identity context.
+    // `kind` is the group prefix; `source` is the identity field to read — both
+    // consumer-controlled, no hardcoded `org:` / `user:` convention anywhere in
+    // the engine. Pure data (no closures), so the schema stays JSON-serializable.
+    // Omit `identityRoles` entirely if you don't need identity-derived scoping.
     identityRoles: [
-      {
-        kind: 'tenant',
-        template: 'org:{id}',
-        extract: (i) => (i.organizationId ? [String(i.organizationId)] : []),
-      },
-      {
-        kind: 'participant',
-        template: 'user:{id}',
-        extract: (i) => (i.userId ? [String(i.userId)] : []),
-      },
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
     ],
   }
 );
@@ -143,11 +135,15 @@ export const schema = defineSchema(
 
 ### Declaring scope on a model
 
-Per-row tenancy and per-entity sync-group anchors live on the
-`defineModel` (or `model(...)`) options. The two halves compose: the
-identity roles above produce a participant's _allowed_ set; the
-per-model options below define how rows are filtered server-side and
-which sync-group label each row fans out on.
+> **Canonical reference: [Identity & Sync Groups](./identity.md).** This is the
+> short version — `scope` (root), `parent` (containment), `grants` (membership),
+> and the model-form `scope` prop are all covered in depth there. Read it once;
+> this guide only shows the minimal shape inline.
+
+Per-row tenancy and per-entity sync-group anchors live on the `model(...)`
+options. The two halves compose: the identity roles above produce a
+participant's _allowed_ set; the per-model options below define how rows are
+filtered server-side and which sync-group each row fans out on.
 
 ```ts
 model(
@@ -159,9 +155,9 @@ model(
     // Rows carry organization_id and bootstrap filters on it.
     orgScoped: true,
 
-    // Per-entity sync-group anchor. Lets a scoped session narrow into
-    // one row's scope via `syncGroupFormat.replace('{id}', rowId)`.
-    syncGroupFormat: 'matter:{id}',
+    // Scope root: rows form the group `matter:<id>`. Children point at it with
+    // `relation.belongsTo('matters', 'matterId', { parent: true })` to inherit.
+    scope: 'matter',
   }
 );
 ```
@@ -178,7 +174,7 @@ Trusted runtimes can use `ABLO_API_KEY`.
 ```ts
 // src/ablo.ts
 import Ablo from '@abloatai/ablo';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
@@ -194,7 +190,7 @@ server API key in the bundle.
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider schema={schema}>{children}</AbloProvider>;
@@ -239,7 +235,7 @@ const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm
 if (!report) throw new Error('report not found');
 ```
 
-Use `retrieve`, `list`, and `count` for synchronous local reads after data has
+Use `retrieve`, `list`, and `count` for synchronous reads after data has
 loaded.
 
 ```ts
@@ -362,7 +358,7 @@ Use a Data Source when your app database remains the source of truth.
 ```ts
 // app/api/ablo/source/route.ts
 import { dataSource } from '@abloatai/ablo';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 import { db } from '@/db';
 
 export const POST = dataSource({
@@ -458,10 +454,10 @@ Keep agent writes on the same schema client surface as the app.
 | `/react`                                  | Live React selectors, provider lifecycle, presence, sync status.  |
 | `/testing`                                | Test harnesses and deterministic mocks.                           |
 | `Data Source`                             | Keep your app database canonical.                                 |
-| `persistence: 'indexeddb'`                | Durable browser cache and offline queueing for apps that need it. |
+| `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
 | `claim` / `claimState` / `queue`          | Show active work and coordinate before a write.                   |
 | `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
-| `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and local-cache tuning.                           |
+| `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
 The first integration should not need most of these. Start with schema and
 model methods, then add the optional pieces where the product actually needs
@@ -472,9 +468,9 @@ them.
 | Method                       | Use it for                                                       |
 | ---------------------------- | ---------------------------------------------------------------- |
 | `load({ where })`            | Async hydration from backing store/server.                       |
-| `retrieve(id)`               | Synchronous local read of one loaded row.                        |
-| `list(options?)`             | Synchronous local collection read.                               |
-| `count(options?)`            | Synchronous local count.                                         |
+| `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.                                  |

package/docs/interaction-model.md

@@ -51,6 +51,9 @@ await ablo.weatherReports.claim(id, async (report) => {
 
 ## Coordination
 
+> Loop view only. Full claim reference — methods, the claim-state object, the
+> `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:
 

package/docs/react.md

@@ -23,7 +23,7 @@ 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 { schema } from '@/ablo/schema';
 
 export function Providers({
   children,
@@ -57,7 +57,7 @@ export function Providers({
 | `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'` pulls the org's baseline before ready; `'none'` skips the baseline and processes live deltas only.|
-| `persistence`       | `'volatile'`           | `'indexeddb'` opts into an offline queue + reload-surviving cache.                                         |
+| `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.                                    |
 
@@ -109,7 +109,7 @@ const reports = useAblo((ablo) =>
   ablo.weatherReports.list({
     where: { projectId },
     filter: (report) => report.status !== 'ready',
-    scope: 'live',
+    state: 'live',
   }),
 );
 ```

package/docs/roadmap.md

@@ -9,15 +9,27 @@ What is shipped, what is next, and what we will not build.
 - **MCP transport** — HTTP server at `/api/mcp`.
 - **TypeScript SDK** — `@abloatai/ablo`, with React bindings.
 - **Dashboard** — keys, audit, metrics, allowed origins.
+- **Schema migrations** — declarative model schema changes. Pure
+  diff/classify/cast-safety/backfill planning engine (`diffSchema`,
+  `classifyMigration`, `classifyCast`, `isAutoApplicable`) ships in the SDK;
+  `ablo generate` emits typed clients from a pushed schema; the server
+  applies and activates migrations only on success.
+- **Structured error contract** — versioned (`ERROR_CONTRACT_VERSION`),
+  drift-guarded code registry shared across the HTTP, WebSocket, and MCP
+  planes, with always-on request ids and an OpenAPI error envelope.
+- **Relation-driven sync groups** — membership-routed fan-out via branded
+  `SyncGroup` + schema-declared identity roles (schema-JSON v2).
+- **Intent coordination plane** — Stripe-shaped `Intent` with per-model
+  `intent(id)` handles for lease/await/commit coordination between agents.
 
 ## In flight
 
-- **Real-time presence** — see who else is viewing/editing a model.
+- **Real-time presence** — see who else is viewing/editing a model
+  (coordination primitives landed; presence surface in progress).
 - **Cross-instance fan-out via Redis** — pub/sub deltas at scale.
 
 ## On deck
 
-- **Schema migrations** — declarative model schema changes.
 - **Field-level subscriptions** — subscribe to one path, not the whole row.
 - **Bulk import/export** — CSV/JSON round-trip with chain verification.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,6 +20,11 @@
       "import": "./dist/schema/index.js",
       "default": "./dist/schema/index.js"
     },
+    "./coordination": {
+      "types": "./dist/coordination/index.d.ts",
+      "import": "./dist/coordination/index.js",
+      "default": "./dist/coordination/index.js"
+    },
     "./react": {
       "types": "./dist/react/index.d.ts",
       "import": "./dist/react/index.js",
@@ -71,6 +76,8 @@
     "build": "npm run clean && tsc -p tsconfig.build.json",
     "pack:check": "npm_config_cache=${TMPDIR:-/tmp}/ablo-npm-cache npm pack --dry-run",
     "lint:imports": "node scripts/check-js-extensions.mjs",
+    "generate:errors": "tsx scripts/generate-error-docs.mts",
+    "lint:errors": "tsx scripts/check-error-docs.mts",
     "lint:pkg": "publint",
     "prepublishOnly": "npm run build && npm run lint:pkg",
     "test": "jest",