@abloatai/ablo 0.34.0 → 0.35.0

package/docs/identity.md

@@ -1,5 +1,7 @@
 # Identity & Sync Groups
 
+> Who is connecting, and which slice of state they are allowed to see.
+
 This is the doc the Quickstart skips: **who is connecting, and which slice
 of shared state do they get?** If you've wired `<AbloProvider client={ablo}>`
 and wondered where org / team / user actually come from — start here.
@@ -20,7 +22,7 @@ that.
 ## What a sync group is
 
 A **sync group** is a named channel of shared state — a string like
-`org:acme` or `deck:abc123`. It is simultaneously:
+`org:acme` or `workspace:abc123`. It is simultaneously:
 
 - **the unit of fan-out** — a confirmed write to a row publishes a delta to
   every participant subscribed to that row's sync group(s), and
@@ -38,7 +40,7 @@ runnable place, so the concepts below have code to attach to.
 The entire declaration surface is: `identityRoles` (who may see what), and on
 each model `scope` / `parent` / `grants` (which group a row fans out on), plus
 optional `syncGroups` at session-mint time (narrowing). Read the three blocks first —
-a human gets their `org` / `team` scope, an agent gets one `deck` — then the
+a human gets their `org` / `team` scope, an agent gets one `workspace` — then the
 sections after explain each.
 
 ```ts
@@ -47,20 +49,18 @@ import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/s
 
 export const schema = defineSchema(
   {
-    // A scope root: its rows form the group `deck:<id>` (kind from `groups.root`).
+    // A scope root: its rows form the group `workspace:<id>` (kind from `groups.root`).
     // Tenant isolation defaults to a row-local `organization_id` column, so no
     // `policy` is needed here.
-    decks: model(
+    workspaces: model(
       { title: z.string(), status: z.enum(['draft', 'published']) },
-      {},
-      { groups: { root: 'deck' } },
+      { groups: { root: 'workspace' } },
     ),
-    // 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 }) },
-      {},
+    // A child: it has no group of its own; it inherits its workspace's group via the
+    // `parent` edge. A write to a document reaches everyone viewing the workspace.
+    documents: model(
+      { workspaceId: z.string() },
+      { relations: { workspace: relation.belongsTo('workspaces', 'workspaceId', { parent: true }) } },
     ),
   },
   {
@@ -88,12 +88,12 @@ export const schema = defineSchema(
 // 3. an AGENT run inherits its user, narrowed to the entities in play.
 // You narrow at SESSION-MINT time: your backend calls `sessions.create` with the
 // agent's allowed `syncGroups`, built from each model's scope via the
-// `syncGroup(kind, id)` helper — never a hand-built `deck:<id>` string. The agent's
+// `syncGroup(kind, id)` helper — never a hand-built `workspace:<id>` string. The agent's
 // runtime then connects with the minted token.
 const session = await server.sessions.create({
   agent: { id: agentId },
-  can: { Deck: ['read', 'update'] },
-  syncGroups: [syncGroup('deck', deckId)], // floor: just the deck it's working on
+  can: { Workspace: ['read', 'update'] },
+  syncGroups: [syncGroup('workspace', workspaceId)], // floor: just the workspace it's working on
 });
 // the agent runtime authenticates with the minted token
 const ablo = Ablo({ schema, apiKey: session.token });
@@ -103,27 +103,27 @@ 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`
+You just saw a human get `org` / `team` groups and an agent get one `workspace`
 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).
+- **Entity groups** — named after *a thing*: `dataroom:{id}`, `workspace:{id}`,
+  `document:{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.
+Agents and people fill that same space differently, and you declare the two in
+different places. An agent's groups come from what it's working on right now, so
+you pass them in code when you start the run. A person's groups come from who
+they are, so you declare them once in the schema.
 
 | | 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 |
+| **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 documents 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.
@@ -135,9 +135,9 @@ depends on *what it's working on*, which is only knowable at dispatch — so you
 pass its `syncGroups` **when your backend mints the agent session**
 (`sessions.create({ agent, can, syncGroups })`). The schema's
 only job for entities is to declare *that* a model is
-entity-scopable and *what its group is named* (`scope: 'deck'` → `deck:{id}`);
+entity-scopable and *what its group is named* (`scope: 'workspace'` → `workspace:{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
+same runtime narrowing — a page scoped to one workspace — 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
@@ -212,7 +212,7 @@ import { defineSchema, identityRole, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
   {
-    decks: model({
+    workspaces: model({
       title: z.string(),
       status: z.enum(['draft', 'published']),
     }),
@@ -247,28 +247,30 @@ declarations, in order of how often you reach for them:
 **`groups.root` — 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>`):
+typename, e.g. typename `SlideDeck` but group `workspace:<id>`):
 
 ```ts
-decks: model({ title: z.string() }, {}, { groups: { root: 'deck' } });
-// a deck row → group `deck:<id>`
+workspaces: model({ title: z.string() }, { groups: { root: 'workspace' } });
+// a workspace row → group `workspace:<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
+(a block → its document → its workspace), 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() },
+documents: model(
+  { workspaceId: z.string(), sourceSlideId: z.string().optional() },
   {
-    deck: relation.belongsTo('decks', 'deckId', { parent: true }),  // ownership → inherit deck:<id>
-    sourceSlide: relation.belongsTo('slides', 'sourceSlideId'),     // reference → NOT routed
+    // default policy: row-local organization_id
+    relations: {
+      workspace: relation.belongsTo('workspaces', 'workspaceId', { parent: true }),  // ownership → inherit workspace:<id>
+      sourceSlide: relation.belongsTo('documents', 'sourceSlideId'),     // reference → NOT routed
+    },
   },
-  {},  // default policy: row-local organization_id
 );
 ```
 
@@ -288,10 +290,12 @@ org membership is already covered by the `org:` identity role.
 dataroomMember: model(
   { userId: z.string(), dataroomId: z.string() },
   {
-    member: relation.belongsTo('users', 'userId'),
-    room: relation.belongsTo('datarooms', 'dataroomId'),
+    relations: {
+      member: relation.belongsTo('users', 'userId'),
+      room: relation.belongsTo('datarooms', 'dataroomId'),
+    },
+    groups: { grants: { subject: 'member', scope: 'room' } },
   },
-  { groups: { grants: { subject: 'member', scope: 'room' } } },
 );
 ```
 
@@ -398,7 +402,7 @@ What carries identity — and just as importantly, what does *not* set the bound
 | ------------ | ------------------------------------------------------------------------------------------------ |
 | `userId` prop | App-level participant id, used for app-owned fields and read by your `identityRole` `source`. **Not** the security boundary — the server enforces scope from the authenticated request. |
 | `teamIds` (on the client) | Team ids expanded into team sync groups via your `identityRoles`.                   |
-| `syncGroups` (at session mint) | Optional. **Narrows** a minted session's subscription to a subset of what auth already allows — it can never widen it. Passed to `sessions.create({ user \| agent, syncGroups })`; build entries with `syncGroup(kind, id)`. Use it to scope an agent (or a focused page's session) to one entity, e.g. `[syncGroup('deck', 'abc123')]`. |
+| `syncGroups` (at session mint) | Optional. **Narrows** a minted session's subscription to a subset of what auth already allows — it can never widen it. Passed to `sessions.create({ user \| agent, syncGroups })`; build entries with `syncGroup(kind, id)`. Use it to scope an agent (or a focused page's session) to one entity, e.g. `[syncGroup('workspace', 'abc123')]`. |
 
 Because the server is the boundary, a client that changes `userId` to another
 user's id does not gain their data — the server resolves and enforces the real
@@ -433,21 +437,21 @@ an entity anchor on the models an agent operates on:
 
 ```ts
 // each scope-root model an agent edits forms a per-entity group
-documents: model({ /* … */ }, {}, { groups: { root: 'document' } }),
-decks:     model({ /* … */ }, {}, { groups: { root: 'deck' } }),
+documents: model({ /* … */ }, { groups: { root: 'document' } }),
+workspaces:     model({ /* … */ }, { groups: { root: 'workspace' } }),
 ```
 
 Then a run subscribes only to the entity groups for the rows it works on — a
 subset of what its user could see:
 
 ```ts
-// agent run triggered by `user`, working on one document + one deck.
+// agent run triggered by `user`, working on one document + one workspace.
 // Your backend mints the agent session narrowed to just the entities in play
 // (the floor). Build each group from the model's scope with `syncGroup(kind, id)`.
 const session = await server.sessions.create({
   agent: { id: agentId },
-  can: { Document: ['read', 'update'], Deck: ['read', 'update'] },
-  syncGroups: [syncGroup('document', documentId), syncGroup('deck', deckId)],
+  can: { Document: ['read', 'update'], Workspace: ['read', 'update'] },
+  syncGroups: [syncGroup('document', documentId), syncGroup('workspace', workspaceId)],
 });
 // identity (the ceiling) is inherited from the triggering user via your
 // session-mint logic; the agent runtime connects with the minted token.
@@ -491,9 +495,9 @@ it claimed.
 ## Narrowing to specific entities
 
 A human gets their full membership automatically (`identityRoles`). There are
-three ways to narrow a participant to specific entities — a page on one deck, or
+three ways to narrow a participant to specific entities — a page on one workspace, or
 an agent pointed at the entities it's working on. You **never hand-write**
-`deck:<id>`; build groups from the model's `scope` (Half 2) with the typed
+`workspace:<id>`; build groups from the model's `scope` (Half 2) with the typed
 `syncGroup(kind, id)` helper from `@abloatai/ablo/schema`.
 
 1. **At session mint — `syncGroups`.** When your backend mints a session, pass the
@@ -501,13 +505,13 @@ an agent pointed at the entities it's working on. You **never hand-write**
    the way to scope a focused page's session):
 
    ```ts
-   // an agent working across two decks and a document
+   // an agent working across two workspaces and a document
    const session = await server.sessions.create({
      agent: { id: agentId },
-     can: { Deck: ['read', 'update'], Document: ['read'] },
+     can: { Workspace: ['read', 'update'], Document: ['read'] },
      syncGroups: [
-       syncGroup('deck', deckA),
-       syncGroup('deck', deckB),
+       syncGroup('workspace', deckA),
+       syncGroup('workspace', deckB),
        syncGroup('document', docId),
      ],
    });
@@ -525,9 +529,9 @@ an agent pointed at the entities it's working on. You **never hand-write**
    [Coordination](./coordination.md).
 
 > **`groups.root` is the schema model option, not a client setting.**
-> `groups: { root: 'deck' }` in `model(...)` declares a scope root
+> `groups: { root: 'workspace' }` in `model(...)` declares a scope root
 > ([Half 2](#half-2--per-model-scope-row--group)) — it names the group
-> (`deck:<id>`) that the mechanisms above then subscribe to.
+> (`workspace:<id>`) that the mechanisms above then subscribe to.
 > There is no `Ablo({ scope })` constructor option. The lifecycle filter on
 > [`list()`](./api.md#model-methods) is a separate axis named **`state`**
 > (`'live' | 'archived' | 'all'`, GitHub's open/closed/all), precisely so it
@@ -536,7 +540,7 @@ an agent pointed at the entities it's working on. You **never hand-write**
 > **Requested groups never grant.** At connect, the server intersects the session's
 > `syncGroups` with what the identity is actually allowed (`requested ∩ allowed`).
 > So `syncGroups` only ever *narrows* within a participant's ceiling — an agent
-> can't reach a deck its capability doesn't already permit, no matter what it
+> can't reach a workspace 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
@@ -583,7 +587,7 @@ The best practices Ablo inherits from that lineage:
    never the boundary. This is why changing `userId` in the browser grants nothing.
 
 3. **Scope by a hierarchical naming convention, declared once.** Ablo's `kind:id`
-   group naming (`org:…` / `team:…` from `identityRoles`, `deck:…` from a model's
+   group naming (`org:…` / `team:…` from `identityRoles`, `workspace:…` 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

package/docs/index.md

@@ -1,101 +1,189 @@
 # Ablo Docs
 
-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.
+> The agentic coordination layer: one API for AI agents, apps, and services to claim, change, and confirm the same rows.
 
-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.
+Two agents reach for the same row. One claims it, does slow work — an LLM call,
+a fetch, a chain of tools — and commits. The second is neither rejected nor
+allowed to clobber: it waits in line, is handed the row as it now stands, and
+proceeds. Contention becomes an ordering problem instead of a retry loop.
 
 ```ts
-// The same call, whether a person, a server action, or an agent makes it.
-await ablo.deck.update({ id: deckId, data: { title: "Q3 Strategy" } });
+// Take the row. Anyone else who wants it waits, then reads it fresh.
+await using claim = await ablo.reports.claim({ id: reportId });
+
+await ablo.reports.update({
+  id: claim.data.id,
+  data: { forecast: await generateForecast(claim.data) },
+  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.
-
-## 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.
-- **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`, 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) — Use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
-- [Integration Guide](./integration-guide.md) — Connect your database via Data Source, plus React, multiplayer, and agent patterns.
-- [Guarantees](./guarantees.md) — What confirmed writes, stale checks, and claims guarantee.
-- [Interaction Model](./interaction-model.md) — The schema, claim, update, confirmation loop.
-- [API Reference](./api.md) — Model-by-model method shape.
-- [Client Behavior](./client-behavior.md) — Options, errors, retries, timeouts, and imports.
-- [Debugging & Logs](./debugging.md) — Turn on the `[Ablo]` coordination trace (`debug` / `logLevel`) to watch claims, queueing, and grants while you build — or read the same activity in code via `ClaimLog` to render an activity feed.
-- [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
-
-| Plane | Primitives | Purpose |
-|---|---|---|
-| State | `Schema`, `Model`, `Claim`, `Receipt` | The product path. Load, coordinate, write, confirm. |
-| Storage | `Data Source` | Your rows live in your own database behind a signed Data Source endpoint. |
-
-## Use cases
-
-- **Let agents write to shared state** — Give an AI agent scoped, revocable write access to your typed data.
-- **Coordinate multiple actors** — Use claims to show pre-write work across humans and agents.
-- **Audit every agent action** — Trace any write back to a human in one query.
-- **Build collaborative editors** — Humans and agents on the same record, with realtime updates and stale-read protection.
-- **Meter and gate API usage** — Per-key, per-team usage reports and quota enforcement.
-- **Integrate with A2A and MCP** — Speak the same protocols as Claude, Cursor, Gemini.
+Claims do not lock. A lock is held against a caller who may never come back; a
+claim is a durable lease with a wait-line behind it, so you can always ask who
+holds a row and who is queued for it. The write returns a receipt, and a write
+based on a row that has since changed is turned away rather than applied.
 
-## Concepts
+## What people build
 
-- [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`, `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).
+<Columns>
+  <Card title="Run agents in parallel" icon="users" href="/coordination">
+    Many agents over one dataset. Claims put them in a line instead of a race.
+  </Card>
+
+  <Card title="Hand work between agents" icon="arrow-left-right" href="/agent-messaging">
+    One agent claims, works, releases. The next picks up with the fresh row and a durable note about why.
+  </Card>
 
-## Examples
+  <Card title="Scope what an agent may write" icon="key-round" href="/api-keys">
+    A revocable key bound to one project's models. Attribution comes from the credential, not the call site.
+  </Card>
+
+  <Card title="Confirm what landed" icon="receipt" href="/guarantees">
+    Every write returns a receipt. Nothing is fire-and-forget, and stale writes are rejected.
+  </Card>
+
+  <Card title="Audit every agent action" icon="scroll-text" href="/audit">
+    Trace any committed change back to the key that made it, and to the person who authorized that key.
+  </Card>
+
+  <Card title="Keep a person in the loop" icon="hand" href="/react">
+    Add the `humans()` plugin and people get presence and live queries. A person's claim is just another holder the agent waits behind.
+  </Card>
+</Columns>
+
+## Using Ablo
+
+<Steps>
+  <Step title="Declare the models agents share">
+    `npx ablo init` scaffolds `ablo/schema.ts`, the typed client, and the type registration.
+    Declare only the models agents coordinate over — your auth, billing, and everything else
+    stay in your own migrations.
+
+    ```bash
+    npx ablo init && npx ablo push
+    ```
+
+    `push` is the step everything depends on: the server keeps its own copy of the schema, and
+    until it has yours, a write to a new model fails with `server_execute_unknown_model`.
+  </Step>
+
+  <Step title="Connect the database the rows live in">
+    Ablo writes through a scoped role and confirms by tailing your write-ahead log. It runs no
+    DDL and owns no schema — your migration tool stays in charge of the shape of your database.
+
+    ```bash
+    npx ablo connect
+    ```
+
+    No database yet? Pass an `apiKey` only and Ablo keeps the rows in its own log, so you can
+    build the whole system today and point it at Postgres when you are ready.
+  </Step>
+
+  <Step title="Build with Ablo">
+    You are writing the agent yourself — a worker, a job handler, a tool inside a model loop.
+    Agents hold no socket; the credential is the identity.
+
+    ```ts
+    const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+    ```
+
+    Read with `list` / `retrieve`, coordinate with `claim`, write with `create` / `update` /
+    `delete`. See [Agents](./agents.md) for the loop and [API Reference](./api.md) for the shape.
+  </Step>
 
-- [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.
-- [Server Agent](./examples/server-agent.md) — Schema-backed worker.
-- [Next.js](./examples/nextjs.md) — App-router setup with React bindings.
+  <Step title="Or point an MCP host at it">
+    The agent is Claude, Cursor, or another MCP host, and you want it operating your data
+    directly. The coordination server exposes the same claim-and-commit loop as tools.
 
-## Runtime builds
+    ```bash
+    claude mcp add ablo -- npx -y @abloatai/mcp
+    ```
 
-- `@abloatai/ablo` — schema-powered sync client for typed model operations, realtime claims, and receipts.
+    See [Model Context Protocol](./mcp.md) — and read the surface table below before you pick,
+    because Ablo publishes two MCP servers and only one of them is a data plane.
+  </Step>
+</Steps>
+
+## Surfaces
+
+Every surface reaches the same coordinated state. Pick by who is calling.
+
+| Surface | Use it for |
+|---|---|
+| **SDK** — `@abloatai/ablo`, `transport: 'http'` | The agents themselves. Stateless, request/response, nothing held open. The main path. |
+| **Coordination MCP** — `@abloatai/mcp` | An agent living inside an MCP host that needs claim and commit as tools. A data plane. |
+| **`humans()`** — with `@abloatai/ablo/react` | The interfaces a person watches agent work arrive in: presence, live queries, a local copy. |
+| **CLI** — `ablo` | Scaffolding, schema push, connecting a database. Terminals and CI. |
+| **REST** — `/api/v1` | Runtimes with no SDK. |
+| **Integration-helper MCP** — hosted `/api/mcp` | Teaching a coding assistant the SDK while you build. Docs, lint, and scaffolds only. |
+
+The two MCP servers are not interchangeable. The coordination server changes
+your data; the integration-helper server serves documentation and has no
+per-model data tools at all. An agent that edits rows uses the SDK or the
+coordination server — never the helper.
+
+### Where people fit
+
+The bare client is the coordination layer: commit, read, observe, claim. People
+are something you add to it. `humans()` is the plugin that declares the local,
+watchable copy — the offline store, live queries, presence, and the framework
+bindings — and it needs a duplex connection, so a stateless agent cannot install
+it and is told so at construction rather than left with a subscription that never
+delivers.
+
+There is no `agents()` plugin, and the absence is the point: agents are the
+default caller, not a special one.
+
+## Concepts
+
+- [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue`: who holds a row, and who is waiting.
+- [Concurrency Convention](./concurrency-convention.md) — the governing rule for how concurrent writes resolve.
+- [Guarantees](./guarantees.md) — what a confirmed write, a stale-write rejection, and a claim each promise.
+- [Idempotency](./idempotency.md) — make a retried write safe; what replays, what re-runs, and for how long.
+- [Schema Contract](./schema-contract.md) — one schema becomes typed clients, agent writes, React reads, and the push.
+- [Agents](./agents.md) — the stateless participant: wake, read, claim, commit, idle.
+- [Agent Messaging](./agent-messaging.md) — durable handoffs between agents, linked to the claim they discuss.
+- [Identity & Sync Groups](./identity.md) — who is connecting, and which slice of state they see.
+- [Interaction Model](./interaction-model.md) — the schema, claim, update, confirmation loop.
+- [Change Propagation](./groups.md) — how one row's change reaches the actors that depend on it.
+- [Client Behavior](./client-behavior.md) — options, errors, retries, timeouts, and imports.
+
+## Authority
+
+- [Projects](./projects.md) — one organization, many apps; each with its own schema, planes, and keys.
+- [API Keys](./api-keys.md) — the credential that carries an agent's identity and its scopes.
+- [Sessions](./sessions.md) — short-lived scoped credentials your backend mints.
+- [Audit Log](./audit.md) — trace any confirmed write back to the person behind it.
+- [Operating on Your Database](./operating-on-your-database.md) — which actions run freely, which to verify first, and which belong to a human.
+- [Session Settings](./session-settings.md) — point your row-level-security policies at Ablo's writes, by naming the settings they already read.
+
+## Build
+
+- [Quickstart](./quickstart.md) — make your first coordinated write.
+- [Integration Guide](./integration-guide.md) — the canonical end-to-end integration.
+- [CLI & Migrations](./cli.md) — `init` / `connect` / `push` / `migrate` / `generate`.
+- [Connect Your Database](./data-sources.md) — where rows land when your own database is canonical.
+- [Deployment](./deployment.md) — the database, the keys, and the schema push that take an integration to production.
+- [React](./react.md) — provider, hooks, and reactive reads.
+- [Webhooks](./webhooks.md) — react to confirmed change from outside the SDK.
+- [Debugging & Logs](./debugging.md) — watch claims, queueing, and grants while you build.
+
+## Reference
+
+- [API Reference](./api.md) — model-by-model method shape.
+- [Errors](./errors.md) — the code registry, its categories, and what to do about each.
+- [Version History & Migration](./migration.md) — every breaking change and its migration.
+- [Changelog](../CHANGELOG.md) — what shipped recently.
+
+## Examples
+
+- [AI SDK Tool](./examples/ai-sdk-tool.md) — put Ablo inside a model's tool call.
+- [Agent + Human](./examples/agent-human.md) — yield when a person is holding the same report.
+- [Server Agent](./examples/server-agent.md) — a schema-backed worker.
+- [Existing Python Backend](./examples/existing-python-backend.md) — add coordination without replacing your API server.
+- [Next.js](./examples/nextjs.md) — app-router setup with React bindings.
 
 ## More
 
 - [README](../README.md) — product overview and first example.
-- [AGENTS.md](../AGENTS.md) — short installation guidance for coding assistants.
-- [Changelog](../CHANGELOG.md) — what shipped recently.
+- [AGENTS.md](../AGENTS.md) — installation guidance for coding assistants.

package/docs/integration-guide.md

@@ -1,11 +1,13 @@
 # Integration Guide
 
-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.
+> The canonical end-to-end integration, added to an existing product one model at a time.
+
+When several AI agents edit the same records in your app — alongside any people
+watching them work — they overwrite each other, and there is no good place to
+coordinate. Ablo gives them one shared, typed write path: the same
+`ablo.<model>.update(...)` call from an agent, a background worker, a server
+action, or a React component. This guide adds it to a product that already has a
+backend and a database, one model at a time.
 
 Three things hold no matter which actor is writing:
 
@@ -79,7 +81,7 @@ and write path are ready for production.
 When handing this to a coding agent, give it a concrete target:
 
 ```txt
-Add Ablo to this app for one model that humans and agents both edit.
+Add Ablo to this app for one model your agents edit.
 Use the org sandbox sk_test_* key. Declare schema, add the Ablo client, replace
 one write with ablo.<model>.update(..., { readAt, onStale: 'reject',
 wait: 'confirmed' }), and add a smoke test for two concurrent writers.
@@ -139,7 +141,6 @@ model(
   {
     /* fields */
   },
-  /* relations */ {},
   {
     // Axis 1 — `policy`: who may READ a row (tenant isolation / RLS). A
     // row-local `organization_id` column is the default, so you omit this for
@@ -256,7 +257,7 @@ refreshes before expiry.
 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)` (positional),
-`getAll({ where })`, and `getCount({ where })` read the already-synced local
+`local.list({ where })`, and `local.count({ where })` read the already-synced local
 graph synchronously, so they're the ones you call in render — and the ones you
 use inside a `useAblo` selector, never the async `retrieve`/`list`.
 
@@ -270,12 +271,12 @@ const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
 if (!report) throw new Error('report not found');
 ```
 
-Use `get`, `getAll`, and `getCount` for synchronous local-graph reads after
+Use `local.retrieve`, `local.list`, and `local.count` for synchronous local-graph reads after
 data has synced.
 
 ```ts
-const report = ablo.weatherReports.get('report_stockholm');
-const activeReports = ablo.weatherReports.getAll({
+const report = ablo.weatherReports.local.retrieve('report_stockholm');
+const activeReports = ablo.weatherReports.local.list({
   where: { projectId: 'proj_123' },
   filter: (report) => report.status !== 'ready',
   orderBy: { updatedAt: 'desc' },
@@ -295,7 +296,7 @@ export function ReportRow({
 }: {
   report: { id: string; location: string; status: string };
 }) {
-  const report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
 
   return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
@@ -375,7 +376,7 @@ 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.get(id)) ?? serverReport` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.local.retrieve(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.
@@ -507,8 +508,8 @@ them.
 | `retrieve({ id })`                     | Async read of one row from the server (await it).                                |
 | `list({ where })`                      | Async read of many rows from the server (await it).                              |
 | `get(id)`                              | Synchronous local read of one synced row (positional id; use in render).         |
-| `getAll({ where })`                    | Synchronous local read of many synced rows.                                      |
-| `getCount({ where })`                  | Synchronous local count of synced rows.                                          |
+| `local.list({ where })`                | Synchronous local read of many synced rows.                                      |
+| `local.count({ where })`               | Synchronous local count of synced rows.                                          |
 | `create({ data, id? })`                | Create through the model client.                                                 |
 | `update({ id, data, ...opts })`        | Update through the model client.                                                 |
 | `delete({ id, ...opts })`              | Delete through the model client.                                                 |