@abloatai/ablo 0.35.0 → 0.36.0

package/docs/deployment.md

@@ -57,10 +57,10 @@ A **plane** is the isolation unit a credential acts on. `production` is the root
 plane; every sandbox sits beside it. Three things are per-plane, and knowing
 which three is most of what production readiness means:
 
-- **Rows** — a sandbox write is invisible to production and to every other sandbox.
-- **The registered database** — one per plane, so your production database and
+- **Rows:** a sandbox write is invisible to production and to every other sandbox.
+- **The registered database:** one per plane, so your production database and
   your dev database are separate registrations.
-- **The active schema artifact** — the model shapes the engine actually routes on.
+- **The active schema artifact:** the model shapes the engine actually routes on.
 
 A key's plane is fixed at mint and spelled in its prefix: `sk_live_` acts on
 production, `sk_test_` on a sandbox. There is no runtime override — the
@@ -219,14 +219,14 @@ handler, the Standard Webhooks signature, and rolling a secret.
 
 ## What to watch once it is live
 
-- **`ablo logs`** — commit activity as it happens, scoped by the key, so a live
+- **`ablo logs`:** commit activity as it happens, scoped by the key, so a live
   key streams the org and a test key streams only its sandbox. `--json` emits
   NDJSON for piping.
-- **`ablo status`** — the readiness verdict. Cheap enough to run from a health
+- **`ablo status`:** the readiness verdict. Cheap enough to run from a health
   check on your own side.
-- **The [audit log](./audit.md)** — every confirmed write traced back to the key
+- **The [audit log](./audit.md):** every confirmed write traced back to the key
   that made it and the person who authorized that key.
-- **Your own logger** — pass `logger` to the client and SDK lifecycle, sync,
+- **Your own logger:** pass `logger` to the client and SDK lifecycle, sync,
   retry, and rollback events join your existing pipeline.
 
 Writes carry receipts rather than being fire-and-forget: a commit is accepted the
@@ -242,7 +242,7 @@ and what each promises.
 | `password authentication failed` during connect | Often a pooled host refusing a session it cannot serve, in the words of a wrong password. | Register the direct database host. |
 | `server_execute_unknown_model` | The plane's active schema does not carry that model. | `ablo push` with a key for that plane. |
 | Clients rejected at connect | The deployed schema and the client's schema disagree. | Push this tree, or deploy the revision the server is running. |
-| `project_scope_denied` (403) | The model belongs to another project in your org. | Use a key minted for that project — a push cannot cross projects. |
+| `project_scope_denied` (403) | The model belongs to another project in your org. | Use a key minted for that project: a push cannot cross projects. |
 | 403 on `ablo push` | The key authenticated but cannot author schema. | A secret `sk_live_`; the `ablo login` live key is observe-only. |
 
 ## The checklist

package/docs/examples/scoped-agent.md

@@ -15,7 +15,7 @@ The three steps below show how to declare it, scope the agent, and write.
 
 See [Identity & Sync Groups](../identity.md) for the full reference.
 
-## 1. Schema — declare the relationship, once
+## 1. Schema: declare the relationship, once
 
 ```ts
 import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/schema';
@@ -44,7 +44,7 @@ export const schema = defineSchema(
 );
 ```
 
-## 2. Dispatch — narrow the agent to the workspace it's working on
+## 2. Dispatch: narrow the agent to the workspace it's working on
 
 An agent can never reach more than the user who triggered it — that's the upper
 limit. From there you narrow it to a single workspace by minting the agent's session
@@ -95,7 +95,7 @@ const ablo = Ablo({
 groups the session asks for with the groups the identity is actually allowed, so
 the agent can never reach a workspace its triggering user couldn't.
 
-## 3. Write — it fans out to everyone on that workspace
+## 3. Write: it fans out to everyone on that workspace
 
 Inside any component under the provider, grab the scoped client with `useAblo()`
 and write. The connection is already narrowed to `workspace:<workspaceId>` from Step 2.

package/docs/groups.md

@@ -38,6 +38,56 @@ never persists work built on a premise it can no longer see.
 
 ---
 
+## How you hear about it
+
+Four channels carry "something changed", and they answer four different
+questions. Pick by the question you have.
+
+```ts
+// A screen that stays current.
+ablo.documents.onChange((docs) => render(docs));
+
+// Who else is in here, and what are they holding.
+await using room = await ablo.documents.join(documentIds, { ttl: '5m' });
+room.peers;
+
+// Stop this write if the thing I read moved while I composed it.
+await ablo.blocks.update({ id, data, reads: [{ group: 'workspace:abc', readAt, onStale: 'notify' }] });
+
+// Tell me later if this moves, even though I am not writing now.
+await ablo.documents.track({ id: 's-1' });
+```
+
+| Question | Channel | Arrives |
+| --- | --- | --- |
+| What do the rows say right now? | `onChange` | As deltas land, on the socket |
+| Who else is working here? | `join`, then `room.peers` and `room.claims` | As participants come and go, on the socket |
+| Did the premise for **this** write move? | `reads` on the write | On that write's receipt, before it applies |
+| Has anything I read moved since? | `track` | On your next commit's receipt |
+
+Two distinctions do most of the work here.
+
+**`join` is about people; `track` is about data.** Both open a subscription and
+both are scoped by sync group, which is why they look alike. `join` reports
+participants: who is present, what they are doing, which rows they hold. `track`
+reports the rows themselves: something you said you cared about moved, here is
+the watermark to re-read it at. A tool that wants to avoid duplicating a peer's
+work needs `join`. A tool whose output goes stale when its inputs change needs
+`track`.
+
+**`reads` guards one write; `track` outlives it.** They speak the same
+vocabulary and produce the same `StaleNotification`. A `reads` entry is checked
+once, at the commit that carried it, and discarded. A `track` is persisted and
+re-checked against every delta after it, so a long-running actor hears about a
+change that landed while it was thinking, on the next commit it makes.
+
+`onChange` and `join` need a live socket, so they are available on the default
+WebSocket client. `reads` and `track` ride the commit, so they reach a socketless
+actor over HTTP too, which is what makes them the notification path for agents
+and workers.
+
+---
+
 ## Three ways a change reaches other rows
 
 "A affects B and C" means three different things. The engine does the first two
@@ -206,8 +256,12 @@ them coarse everywhere else.
 
 ## Where this is defined
 
-- **Access** — who may read or write a group — is [`identity.md`](./identity.md).
-- **The convention** — non-coercion, the premise, and the notification — is
+- **Access**, meaning who may read or write a group, is
+  [`identity.md`](./identity.md).
+- **The convention** behind non-coercion, the premise, and the notification is
   [`concurrency-convention.md`](./concurrency-convention.md) (§4 and §5).
-- **The mechanics** — the three coordination blocks underneath — are
+- **The mechanics**, the three coordination blocks underneath, are
   [`coordination.md`](./coordination.md).
+- **`join` and presence**, the participant half of the table above, are
+  [`coordination.md`](./coordination.md) for the claim stream and
+  [`react.md`](./react.md) for `useJoin`.

package/docs/guarantees.md

@@ -65,11 +65,13 @@ await ablo.weatherReports.update({
 `onStale: 'reject'` prevents lost updates. If the target changed after the
 snapshot, the server rejects the write instead of applying stale reasoning.
 
-Advanced policies exist for controlled product flows:
+Two other dispositions exist. `overwrite` applies the write with no stale check
+at all. `notify` **holds** the write, so the row is left as it stands, and hands
+back a `StaleNotification` carrying the current value for the actor to reconcile
+and re-issue; the rest of the batch still commits.
 
-- `reject` fails the write when state moved.
-- `overwrite` applies the write without stale protection.
-- `notify` accepts the write and marks it for product review.
+See [Concurrency Convention](./concurrency-convention.md) for the full taxonomy,
+what each disposition is checked against, and where the convention stops.
 
 ## Claim Coordination
 
@@ -99,14 +101,39 @@ Agents should import the same schema as the app and write through
 
 ## Audit Trail
 
-Accepted writes can be attributed to:
+Attribution is not a separate log you opt into. It rides on the change itself.
+Every broadcast delta names the actor, the authority it acted under, the
+credential that authorized it, and the approval stage it was in:
 
-- the actor that wrote,
-- the human or system the actor worked on behalf of,
-- the model, operation, and state cursor.
+```ts
+{
+  modelName:         'weatherReports',
+  modelId:           'report_stockholm',
+  actionType:        'U',
+  actor:             { kind: 'agent', id: 'weather-agent-v3' },
+  onBehalfOf:        { kind: 'user',  id: 'user_8f2a' },
+  capabilityId:      '…',       // the key the write was authorized by
+  confirmationState: 'auto',    // previewed | approved | required_human_approval
+  createdAt:         '2026-05-14T14:22:01.034Z',
+}
+```
+
+`actor` and `onBehalfOf` are derived from the credential, not from the call site,
+so an agent cannot name a different actor in its own write. `capabilityId` is
+non-null for every agent and system commit, so a write can always be traced to
+the key that made it, and from that key to the person it was issued to.
+
+The stored history goes one step further than recording. Audit rows are chained
+with a keyed hash, so the log is tamper-*evident*: `verify-chain` walks the chain
+and, if it breaks, names the sequence number and the hashes that disagree. No
+chain roots at an agent. The delegation root is always the person who set the
+work in motion.
+
+For agent work this is what answers, after the fact: what changed, who authorized
+it, which run did it, and whether a human was in the loop.
 
-For agent work, this is what lets an audit surface answer: "what changed, who
-authorized it, which run did it, and what state was it based on?"
+See [Audit Log](./audit.md) for the stored row shape, the filters, verification,
+and export.
 
 ## Persistence
 

package/docs/how-it-works.md

@@ -13,13 +13,13 @@ await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confir
 const task = ablo.tasks.local.retrieve('task_42');
 ```
 
-## The mental model — read this once
+## The mental model: read this once
 
 Ablo is a **coordination layer in front of your Postgres**. Agents, background
 jobs, and the people alongside them all change the same application data through
 one API, and Ablo makes sure their writes don't clobber each other.
 
-- **Writes go through Ablo.** `ablo.<model>.create / update / delete` enter Ablo's
+- **Writes go through Ablo:** `ablo.<model>.create / update / delete` enter Ablo's
   commit chokepoint — where claims, ordering, and idempotency are enforced — and
   Ablo applies the change to your Postgres through a scoped writer role. The commit
   is accepted (`queued`) the moment Ablo takes it.
@@ -37,17 +37,41 @@ one API, and Ablo makes sure their writes don't clobber each other.
 That's the shape: **you write through Ablo → it lands in your Postgres → the WAL
 echo confirms it → everyone connected sees it live.**
 
+## The primitives
+
+| Primitive | Plane | Purpose |
+|---|---|---|
+| `Schema` | State | Declares typed models the app and agents can read and write. |
+| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async reads), `local.retrieve`/`local.list`/`local.count` (the same verbs, synchronous and local-only), `create`, `update`, and `delete`. |
+| `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral, never persisted. |
+| `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
+| `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |
+
+### Why each primitive is separate
+
+Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
+does a job the others cannot. If you are coming from Replicache or Yjs you would
+expect just `Commit`. Here is what the other two buy you over that minimum:
+
+- **`Claim` is not a read lock.** Reads stay open. Claims serialize
+  acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
+  from fresh state.
+- **`Receipt` is not a `200 OK`.** It is the durable artifact a commit produced:
+  accepted commit id, server-assigned timestamps, stale-check outcome. It is
+  addressable after the fact and replayable into a different client. A status
+  code cannot be re-read by a sub-agent that was not on the original call.
+
 ## Where your data lives
 
 You point Ablo at a Postgres database, and that's where its rows live. Only *which*
 database differs by environment — the code is identical.
 
-- **Production** — your Postgres. `ablo connect` sets up a scoped writer role and
+- **Production:** your Postgres. `ablo connect` sets up a scoped writer role and
   logical replication; your rows live in your database, and Ablo writes to them
   through that role.
-- **Sandbox and local dev** — a separate or local Postgres you can throw away. Same
+- **Sandbox and local dev:** a separate or local Postgres you can throw away. Same
   models, same code, a different database behind them.
-- **Before you connect one** — Ablo keeps state in its own log, so you can build the
+- **Before you connect one.** Ablo keeps state in its own log, so you can build the
   whole app today and point it at a real database when you're ready.
 
 Registering the database is the whole switch. There is no tier or flag to choose.

package/docs/idempotency.md

@@ -35,10 +35,10 @@ The key is not a lookup that happens before the write — it is the **execution
 itself**. Ablo inserts a pending row keyed by the caller and the key inside the same transaction as
 the mutation, and a unique index makes that insert the lock:
 
-- **Insert wins** — this transaction owns the execution and runs the write.
-- **Insert conflicts** — someone else owns it. The second caller waits for the owner to finish and
+- **Insert wins:** this transaction owns the execution and runs the write.
+- **Insert conflicts:** someone else owns it. The second caller waits for the owner to finish and
   then replays its recorded result.
-- **Insert conflicts, different request** — the key was reused to mean something else. Rejected.
+- **Insert conflicts, different request:** the key was reused to mean something else. Rejected.
 
 Because the lock and the write share a transaction, there is no window in which a write has happened
 but its key has not been recorded.
@@ -52,7 +52,7 @@ same key string without colliding, and one agent can never replay another's resu
 |---|---|
 | A new key | Runs the write. |
 | The same key, the same request, already finished | Replays the recorded result. The write does not run again. |
-| The same key, the same request, still running | Waits for the in-flight attempt, then replays its result. If the original is still running after a short wait, rejects with `idempotency_conflict` (409) — retry the same key. |
+| The same key, the same request, still running | Waits for the in-flight attempt, then replays its result. If the original is still running after a short wait, rejects with `idempotency_conflict` (409): retry the same key. |
 | The same key, a **different** request | Rejects with `idempotency_conflict` (409). A key is bound to the request it first arrived with. |
 
 Both conflict cases return the same code, so tell them apart by what your own
@@ -60,7 +60,7 @@ client did. If you retried an identical request, the original is still in flight
 — wait and retry the same key. If you changed the request, that is a client bug:
 use a new key.
 
-## Failures are not replayed — they re-run
+## Failures are not replayed: they re-run
 
 This is where Ablo deliberately differs from Stripe and from most payment APIs, and it is the
 behaviour most likely to surprise you.
@@ -106,7 +106,7 @@ may already have committed. Restore the original route and retry the same key.
 | Timeout or dropped connection, no response | Retry with the **same** key, with backoff. You get the recorded success, or the write runs now. |
 | `source_unreachable` (503) | Retry with the **same** key once connectivity recovers. The write stays pinned to its route. |
 | `replication_lag_timeout` (504) | The write may have materialized. Retry with the **same** key, or wait for source ingestion to catch up. |
-| `AbloStaleContextError` | Re-read the row, regenerate, then write under a **new** key — the new write is a new intention. |
+| `AbloStaleContextError` | Re-read the row, regenerate, then write under a **new** key: the new write is a new intention. |
 | `AbloClaimedError` | Someone else holds the row. Wait or yield; the key is unused, so reuse it when you retry. |
 | `idempotency_conflict` (409) after an identical retry | The original is still in flight. Wait, then retry the **same** key. |
 | `idempotency_conflict` (409) after changing the request | A client bug: a key is bound to the first request sent under it. Use a **new** key. |

package/docs/identity.md

@@ -24,9 +24,9 @@ that.
 A **sync group** is a named channel of shared state — a string like
 `org:acme` or `workspace:abc123`. It is simultaneously:
 
-- **the unit of fan-out** — a confirmed write to a row publishes a delta to
+- **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
-- **the unit of access** — a participant receives a row's deltas *only if* the
+- **the unit of access:** a participant receives a row's deltas *only if* the
   row's sync group is in their allowed set.
 
 There is no built-in `org` / `team` / `user` concept in the engine. Those are
@@ -101,16 +101,16 @@ const ablo = Ablo({ schema, apiKey: session.token });
 
 That's the whole surface. The rest of this doc is the *why* behind each line.
 
-## Two kinds of group — the whole mental model
+## Two kinds of group: the whole mental model
 
 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}`,
+- **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}`, `workspace:{id}`,
+- **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.
@@ -122,8 +122,8 @@ 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 documents it has read — never beyond what its user's membership could reach |
+| **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 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.
@@ -197,7 +197,7 @@ Scoping is two declarations that meet in the middle. One describes the
 (which group does this row belong to?). A participant sees a row **iff** the
 row's sync group is in the participant's allowed set.
 
-### Half 1 — `identityRoles`: identity → allowed groups
+### Half 1 (`identityRoles`): identity → allowed groups
 
 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`)
@@ -238,7 +238,7 @@ in-process and on a hosted server that only ever sees the compiled JSON.
 > `user:{id}` role above already covers it — see
 > [Agents are participants too](#agents-are-participants-too).
 
-### Half 2 — per-model scope: row → group
+### Half 2 (per-model scope): row → group
 
 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
@@ -310,7 +310,7 @@ options as `tenancy-option-removed` errors and steers you to `policy: { by:
 explicit `policy: { by: 'none' }`. See
 `packages/sync-engine/src/schema/model.ts` for the full option set.
 
-## How identity reaches Ablo — the proxy model
+## How identity reaches Ablo: the proxy model
 
 This is the part the README's "authenticates with the signed-in user's
 session" glossed over. Concretely:
@@ -400,9 +400,9 @@ What carries identity — and just as importantly, what does *not* set the bound
 
 | Where        | Purpose                                                                                          |
 | ------------ | ------------------------------------------------------------------------------------------------ |
-| `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. |
+| `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('workspace', '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
@@ -431,7 +431,7 @@ agent authority = (triggering user's allowed set)    ← ceiling, inherited (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
+([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:
 
@@ -475,22 +475,21 @@ not *what's reachable*.
 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
+- **Inherit the user, and no more:** the OAuth
   [on-behalf-of](https://workos.com/blog/oauth-on-behalf-of-ai-agents) model: the
   agent's reach is tied to the consenting user, never the org.
-- **Least privilege, just-in-time** — scoped to the task's entities, not standing
+- **Least privilege, just-in-time:** scoped to the task's entities, not standing
   org-wide access (the over-privilege pattern
   [OWASP's NHI Top 10](https://www.token.security/assets/the-ultimate-non-human-identity-security-guide)
   flags as the dominant agent risk).
-- **Dual-principal attribution** — record both the executing agent and the
+- **Dual-principal attribution:** record both the executing agent and the
   triggering human.
 
 Identity is 1:1 with a human participant; authority is narrowed to the work. That
 split is what lets Ablo keep *one model API for every actor* without ever
 granting an agent standing access to everything its user can see. The agent that
-runs the [Coordinating long agent work](../README.md#coordinating-long-agent-work)
-`claim` loop is, to the scoping layer, that same participant — scoped to the row
-it claimed.
+runs the [Coordination](./coordination.md) `claim` loop is, to the scoping layer,
+that same participant — scoped to the row it claimed.
 
 ## Narrowing to specific entities
 
@@ -530,7 +529,7 @@ an agent pointed at the entities it's working on. You **never hand-write**
 
 > **`groups.root` is the schema model option, not a client setting.**
 > `groups: { root: 'workspace' }` in `model(...)` declares a scope root
-> ([Half 2](#half-2--per-model-scope-row--group)) — it names the group
+> ([Half 2](#half-2-per-model-scope-row--group)) — it names the group
 > (`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`**
@@ -543,7 +542,7 @@ an agent pointed at the entities it's working on. You **never hand-write**
 > 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
+## How this compares, and the best practices it follows
 
 Ablo's identity model is not novel; it's the convergent answer every serious
 realtime / sync SDK arrived at. Knowing which industry pattern it *is* tells you
@@ -551,7 +550,7 @@ how to reason about it.
 
 **Realtime authorization splits into two shapes.** Ablo is firmly in the first:
 
-- **Server derives scope from authenticated identity** — the server decides what
+- **Server derives scope from authenticated identity:** the server decides what
   a participant may read/write and the client cannot override it. This is Ablo's
   proxy model. It's the same shape as
   [Supabase Realtime's RLS-on-connect](https://supabase.com/docs/guides/realtime/authorization)
@@ -560,7 +559,7 @@ how to reason about it.
   checks the permissions for you" — recommended for production), and
   [ElectricSQL **proxy auth**](https://electric-sql.com/docs/guides/auth) (a
   reverse-proxy sets shape params server-side before forwarding).
-- **Client proposes, server authorizes the exact request** — the client names
+- **Client proposes, server authorizes the exact request:** the client names
   the room/shape and the server signs off, as in
   [Pusher's channel authorization endpoint](https://pusher.com/docs/channels/server_api/authorizing-users/),
   [ElectricSQL **gatekeeper auth**](https://github.com/electric-sql/electric/blob/main/examples/gatekeeper-auth/README.md),

package/docs/index.md

@@ -1,6 +1,6 @@
 # Ablo Docs
 
-> The agentic coordination layer: one API for AI agents, apps, and services to claim, change, and confirm the same rows.
+> Collaboration infrastructure for AI agents: one API for agents, apps, and services to claim, change, and confirm the same rows.
 
 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
@@ -110,12 +110,12 @@ 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. |
+| **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
@@ -136,6 +136,7 @@ default caller, not a special one.
 
 ## Concepts
 
+- [How Ablo Works](./how-it-works.md) — the mental model in one page: you write through Ablo, it lands in your Postgres, the write-ahead log confirms it. **Read this first.**
 - [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.
@@ -144,7 +145,6 @@ default caller, not a special one.
 - [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.
 

package/docs/integration-guide.md

@@ -11,7 +11,7 @@ backend and a database, one model at a time.
 
 Three things hold no matter which actor is writing:
 
-- **One model API for every actor.** `ablo.<model>.update(...)` is what
+- **One model API for every actor:** `ablo.<model>.update(...)` is what
   React components, server actions, background workers, and AI agents
   all call. No separate "agent SDK," no parallel mutation path. The
   attribution comes from the credential, not the call site.
@@ -351,8 +351,19 @@ server   -> ablo.weatherReports.update(...)
 Ablo coordinates those writes, fans out confirmed deltas, exposes active claims,
 and lets callers reject stale writes with `readAt`.
 
-Direct writes to your own database bypass that stream until your app reports the
-change through Data Source events.
+A write that reaches your database some other way still reaches connected
+clients. A `psql` session, a cron job, an admin tool, a legacy endpoint: Ablo
+tails your write-ahead log, so a change it did not make is picked up and fanned
+out like any other, attributed to the data source rather than to an agent.
+
+What such a write does not get is the coordination. It never entered the commit
+chokepoint, so no claim was checked, no `readAt` was compared, and no idempotency
+key was honoured. It can land on top of a row an agent is holding. Route anything
+that must respect a claim through `ablo.<model>`.
+
+On the [Data Source endpoint fallback](./data-sources.md) there is no replication
+stream to tail, and there the original caveat holds: a direct write stays
+invisible until your app reports it through Data Source events.
 
 ## 6. Existing API Backend
 

package/docs/mcp.md

@@ -6,7 +6,7 @@ Ablo publishes **two** MCP servers for two different jobs. Don't confuse them:
 
 | Server | Purpose | Auth | Tools |
 |---|---|---|---|
-| **Coordination** (`@abloatai/mcp`) | Manage your Ablo the way the CLI does, and let an agent safely read & mutate application data | API key (`sk_…` / `rk_…`) | projects, schema, logs, usage — plus `get` / `list` / `create` / `update` / `delete` / `claim` / `release` over your rows |
+| **Coordination** (`@abloatai/mcp`) | Manage your Ablo the way the CLI does, and let an agent safely read & mutate application data | API key (`sk_…` / `rk_…`) | projects, schema, logs, usage: plus `get` / `list` / `create` / `update` / `delete` / `claim` / `release` over your rows |
 | **Integration-helper** (hosted `/api/mcp`) | Help an AI coding assistant write SDK integration code that compiles | none (public docs) | doc search, export surface, schema lint, scaffold |
 
 The coordination server manages your account **and is the data plane** — it is
@@ -37,7 +37,7 @@ claude mcp add ablo -- npx -y @abloatai/mcp
 | `list_projects` | `ablo projects list` | the org's projects (needs `sk_`) |
 | `create_project` | `ablo projects create` | create one (needs `sk_`) |
 | `tail_logs` | `ablo logs` | recent commits and the actor behind each |
-| `get_usage` | — | usage in daily buckets |
+| `get_usage` |: | usage in daily buckets |
 
 There are no key-management tools. A mint returns the plaintext once — only a
 hash is kept — so no tool can hand it back later, and returning it at mint time
@@ -63,7 +63,7 @@ Each tool mirrors an SDK verb, scoped to a model + id. Model names come from
 | `update_model` | `ablo.<model>.update({ id, … })` | guarded update |
 | `delete_model` | `ablo.<model>.delete({ id })` | guarded delete |
 | `claim_model` | `ablo.<model>.claim({ id })` | acquire / queue a coordination lease |
-| `release_claim` | — | release the lease so others proceed |
+| `release_claim` |: | release the lease so others proceed |
 
 The agent-facing contract — the safe loop, the "derive idempotency keys from
 the business event" rule, and the error-code playbook — ships as a loadable
@@ -94,9 +94,9 @@ claude mcp add --transport http ablo https://<your-app>/api/mcp
 
 The endpoint is identical for every client — only the config surface differs:
 
-- **Claude Code** — run the `claude mcp add` command above; verify with `/mcp list`, remove with `claude mcp remove ablo`.
-- **Cursor** — add the server to `~/.cursor/mcp.json` (macOS / Linux), then restart.
-- **Windsurf** — add the same JSON via Settings → Cascade → MCP, then restart.
+- **Claude Code:** run the `claude mcp add` command above; verify with `/mcp list`, remove with `claude mcp remove ablo`.
+- **Cursor:** add the server to `~/.cursor/mcp.json` (macOS / Linux), then restart.
+- **Windsurf:** add the same JSON via Settings → Cascade → MCP, then restart.
 
 Cursor and Windsurf use the same config shape:
 
@@ -120,7 +120,7 @@ Each client then lists the Ablo tools (`search_ablo_docs`, `get_recipe`, `get_ap
 | `get_recipe` | Returns the full markdown of one doc by name (e.g. `readme`, `quickstart`, `schema-contract`, `integration-guide`, `api`, `guarantees`). |
 | `get_api_surface` | Returns the structured export list for an SDK subpath (`@abloatai/ablo`, `./react`, `./schema`, `./testing`, …). Call with no argument to list every subpath. |
 | `validate_schema` | Lints `defineSchema` source against the DSL rules (camelCase fields, lowercase model keys, `scope`/`grants` sync groups, valid `load` strategies, no legacy builders) and returns a structured issue list. Runs no code. |
-| `scaffold_app` | Emits a starter file tree for a schema-first integration — `next`, `node-agent`, or `plain`, with a `data-source` (your own database) endpoint. |
+| `scaffold_app` | Emits a starter file tree for a schema-first integration: `next`, `node-agent`, or `plain`, with a `data-source` (your own database) endpoint. |
 
 #### Resources