@abloatai/ablo 0.6.0 → 0.8.0

package/docs/guarantees.md

@@ -1,7 +1,14 @@
 # Guarantees
 
-This page is the short contract for what Ablo guarantees at the state
-boundary.
+When an Ablo write succeeds, the server has accepted it — and when two people or
+agents touch the same row, Ablo coordinates them instead of letting one silently
+overwrite the other. This page is the precise list of what you can count on:
+confirmed writes, stale-write protection, claims, and the audit trail behind
+every change.
+
+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.
 
 ## Confirmed Writes
 
@@ -17,8 +24,9 @@ const updated = await ablo.weatherReports.update(
 ```
 
 If the call resolves, the write was accepted by the server. If it rejects, the
-error explains whether the write was rejected for auth, validation, stale state,
-active claim conflict, idempotency, rate limit, or transport failure.
+typed error tells you exactly why — the most common reasons being failed
+authorization, a schema validation error, or a stale-state or claim conflict
+(each covered below).
 
 Schema model writes return the updated model row.
 
@@ -58,24 +66,28 @@ Advanced policies exist for controlled product flows:
 - `reject` fails the write when state moved.
 - `force` applies the write without stale protection.
 - `flag` accepts the write and marks it for product review.
-- `merge` is reserved for server-defined merge behavior.
+
+`merge` is not yet available.
 
 ## Claim Coordination
 
+> The guarantee, not the how-to. Methods, the claim-state object, and the `claim.queue`
+> live in [Coordination](./coordination.md).
+
 Claims are live coordination signals. They are not database locks.
 
-Claims are **advisory** and **cooperative**. `ablo.<model>.claim(id, ...)`
-serializes on contention: if another human or agent 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 are open by default —
-`ablo.<model>.claimState(id)` returns the current claim state (or `null`) without
-ever blocking. Server/model reads can opt into `ifClaimed: 'wait'` or
-`ifClaimed: 'fail'` when they should not read through active work.
+`ablo.<model>.claim(id, ...)` serializes on contention: if another human or agent
+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.
 
 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
-`ablo.<model>.update(id, ...)` is stale-guarded and rejects with
-`AbloStaleContextError` if the row advanced past your claim point.
+`ablo.<model>.update(id, ...)` is rejected with `AbloStaleContextError` if the row
+changed underneath you after your claim point.
 
 ## Agent Runs
 
@@ -95,10 +107,10 @@ authorized it, which run did it, and what state was it based on?"
 
 ## Persistence
 
-Ablo defaults to volatile local persistence. That keeps the SDK focused on
-coordination and audit instead of silently becoming a browser storage product.
+Ablo defaults to volatile in-memory persistence, so nothing is written to disk
+unless you ask for it.
 
-Opt into durable browser cache and offline queueing when you need it:
+Opt into a durable browser cache that survives reloads when you need it:
 
 ```ts
 const ablo = Ablo({

package/docs/identity.md

@@ -30,12 +30,76 @@ 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.
+something **you declare in your schema**. Here is that whole declaration in one
+runnable place, so the concepts below have code to attach to.
 
-### Two kinds of group — the whole mental model
+## 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). 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
+import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/schema';
 
-Every sync group is named after one of two things, and that's the cleanest way
-to hold the model in your head:
+export const schema = defineSchema(
+  {
+    // 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, 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 `kind` (the group prefix) and the identity
+    // `source` field to read. No closures — so the schema stays JSON-serializable.
+    identityRoles: [
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
+      identityRole({ kind: 'team', source: 'teamIds', multi: true }),
+    ],
+  },
+);
+```
+
+```tsx
+// 2. app/providers.tsx — a HUMAN gets their full org / team scope
+<AbloProvider schema={schema} userId={user.id} teamIds={user.teamIds}>
+  {children}
+</AbloProvider>
+```
+
+```tsx
+// 3. an AGENT run inherits its user, narrowed to the entities in play.
+// Pass the MODEL form — { decks: id } — not a hand-built `deck:<id>` string;
+// the engine derives the group from each model's `scope`.
+<AbloProvider
+  schema={schema}
+  userId={user.id}                // ceiling: the triggering user
+  scope={{ decks: deckId }}       // floor: just the deck it's working on
+>
+  {children}
+</AbloProvider>
+```
+
+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
@@ -45,9 +109,10 @@ to hold the model in your head:
   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):
+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 |
 | --- | --- | --- | --- |
@@ -57,12 +122,13 @@ identity) while entity scope is dynamic (a property of the task):
 > **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* (`entity: 'deck'` → `deck:{id}`);
+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.)
@@ -83,62 +149,6 @@ The identity is a **participant** — and a participant is either a human
 [Agents are participants too](#agents-are-participants-too) below. Everything in
 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.
-
-```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';
-
-export const schema = defineSchema(
-  {
-    conversations: model(
-      { title: z.string(), createdBy: z.string() },
-      {},
-      { orgScoped: true, syncGroupFormat: 'conversation:{id}' },
-    ),
-    decks: model(
-      { title: z.string(), status: z.enum(['draft', 'published']) },
-      {},
-      { orgScoped: true, syncGroupFormat: 'deck:{id}' },
-    ),
-  },
-  {
-    // 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.
-    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 }),
-    ],
-  },
-);
-```
-
-```tsx
-// 2. app/providers.tsx — a HUMAN gets their full org / team scope
-<AbloProvider schema={schema} userId={user.id} teamIds={user.teamIds}>
-  {children}
-</AbloProvider>
-```
-
-```tsx
-// 3. an AGENT run inherits its user, narrowed to the entities in play
-<AbloProvider
-  schema={schema}
-  userId={user.id}                                                  // ceiling: the triggering user
-  syncGroups={[`conversation:${conversationId}`, `deck:${deckId}`]} // floor: just its work
->
-  {children}
-</AbloProvider>
-```
-
-That's the whole surface. The rest of this doc is the *why* behind each line.
-
 ## The two halves of scoping
 
 Scoping is two declarations that meet in the middle. One describes the
@@ -148,15 +158,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 +178,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 +199,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
+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
-model(
-  { /* fields */ },
-  { /* relations */ },
+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 +304,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,
@@ -311,27 +360,29 @@ 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
-// 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 }}
 >
 ```
 
@@ -348,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
@@ -368,24 +419,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 +503,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

@@ -1,36 +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.
+- [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.
@@ -38,6 +49,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
@@ -58,19 +70,23 @@ 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.
+- [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 +99,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.