@abloatai/ablo 0.31.0 → 0.33.0

package/docs/audit.md

@@ -2,33 +2,40 @@
 
 The audit log records who changed what in your org, and when — including
 changes an AI agent made on a person's behalf. Every change is one row, and the
-rows are signed in a chain so you can later prove the history wasn't altered.
-You can filter it, page through it, and export it.
-
-Every commit becomes one row.
+rows are chained with a keyed hash (HMAC-SHA256) so you can later prove the
+history wasn't altered. You can filter it, page through it, and export it.
 
 ## Row shape
 
+Each stored row carries both the attribution fields — who acted, on whose behalf,
+with which key — and the chain columns that make the log tamper-evident:
+
 ```ts
 {
-  occurredAt:           '2026-05-14T14:22:01.034Z',
-  actorKind:            'user' | 'agent' | 'system',
-  actorId:              string,
-  onBehalfOfKind:       'user' | 'agent' | 'system' | null,
-  onBehalfOfId:         string | null,
-  capabilityId:         string | null,    // the API key/capability used for the write
-  capabilityLabel:      string | null,    // its human-readable name, for scanning the log
-  delegationChainRoot:  string | null,    // always points at a human
-  actionType:           string,           // e.g. 'weatherReport.update'
-  modelName:            string | null,    // e.g. 'claude-opus-4-7'
-  diffSummary:          unknown,
-  // tamper-evident
-  chainSeq:             number,
-  prevHash:             string,
-  rowHash:              string,
+  id:                        string,
+  occurredAt:                '2026-05-14T14:22:01.034Z',
+  actorKind:                 'user' | 'agent' | 'system',
+  actorId:                   string,
+  onBehalfOfKind:            'user' | 'agent' | 'system' | null,
+  onBehalfOfId:              string | null,
+  capabilityId:              string | null,    // the API key/capability used for the write
+  capabilityLabel:           string | null,    // its human-readable name, for scanning the log
+  delegationChainRootUserId: string | null,    // always points at a human
+  actionType:                string,           // e.g. 'weatherReport.update'
+  modelName:                 string,            // e.g. 'claude-opus-4-8'
+  confirmationState:         'auto' | 'previewed' | 'approved' | 'required_human_approval' | 'auto_historical',
+  diffSummary:               unknown,
+  // chain columns — carried on every stored row, checked by verify (below)
+  chainSeq:                  number,
+  prevHash:                  string,
+  rowHash:                   string,
 }
 ```
 
+`confirmationState` records whether an agent's write ran on its own (`auto`), was
+shown first (`previewed`), was signed off (`approved`), or is still waiting on a
+person (`required_human_approval`) — it's also a filter on the list endpoint.
+
 ## Delegation chain
 
 Every action traces back to a human. Even when an agent makes the change,
@@ -53,9 +60,14 @@ or, on tamper:
 
 ```json
 { "ok": false, "brokenAtSeq": 8419, "reason": "hash_mismatch",
-  "expectedHash": "sha256:…", "foundHash": "sha256:…" }
+  "expectedHash": "a3f1c9…", "foundHash": "b7e04d…" }
 ```
 
+Hashes come back as plain hex. `expectedHash`/`foundHash` accompany a
+`hash_mismatch` or `prev_hash_mismatch`; the other reasons (`sequence_gap`,
+`missing_root`, `no_rows`) stand on their own. Recomputing a row's hash needs the
+org's HMAC key, so verification runs where that secret is available.
+
 ## Filter and paginate
 
 The dashboard at `/[orgSlug]/audit` is the UI for this. The same filters
@@ -82,6 +94,6 @@ JSON `GET` endpoint above using `nextCursor`.
 ## Compliance posture
 
 The [audit log landing page](/audit-log) is the marketing-side description.
-The verifier's hash algorithm and chain semantics live in the
-`@ablo/audit-chain` package — embeddable if you need to verify chains in a
-detached service.
+The HMAC-SHA256 chain algorithm and its semantics live in the
+`@ablo/audit-chain` package — the reference implementation, embeddable if you
+need to verify chains in a detached service (given the org's HMAC key).

package/docs/client-behavior.md

@@ -39,8 +39,9 @@ Common options:
 | `dangerouslyAllowBrowser` | Required before sending an API key from browser code. Prefer a server route instead. |
 
 Your database connects out of band — through logical replication (`npx ablo
-connect`) or a signed [Data Source](./data-sources.md) endpoint — so the client
-holds only `apiKey`, never a connection string. See
+connect`), or the signed [Data Source](./data-sources.md) endpoint as the
+fallback for databases that can't grant replication — so the client holds only
+`apiKey`, never a connection string. See
 [Connect Your Database](./data-sources.md) for the full setup.
 
 ## Model Methods
@@ -95,8 +96,10 @@ such as `useAblo((ablo) => ablo.weatherReports.claim.state({ id }))`
 receive active claim state. There is
 no extra multiplayer setup beyond routing shared state through Ablo.
 
-If an app writes directly to its database, Ablo cannot coordinate that write
-until the app reports it through Data Source events.
+Writes flow through Ablo's commit chokepoint and land in your database, so every
+actor routing through Ablo is coordinated. The one write it can't coordinate is
+one made directly against your database, around Ablo — the WAL echo still catches
+it for reads, but it bypasses claims and ordering.
 
 ## Per-Write Options
 

package/docs/concurrency-convention.md

@@ -161,7 +161,7 @@ and `currentValues` is empty (re-read the group).
 
 What the convention **guarantees**, and where it **stops**:
 
-1. **Engine surfaces, actor decides.** For `flag`/`merge` the engine never
+1. **Engine surfaces, actor decides.** Under `notify` the engine never
    repairs, merges, or re-plans. It reports `currentValues` and the actor (agent
    or human) owns the resolution. The engine does not distinguish them — it is
    actor-neutral by design.
@@ -179,7 +179,7 @@ What the convention **guarantees**, and where it **stops**:
    shared database, which are inherently reversible (prior value in
    `sync_deltas`). **Irreversible external side-effects** (emails, payments,
    third-party calls) are *out of scope* — the engine cannot hold or undo them,
-   so they must not be gated by `flag`/`merge`.
+   so they must not be gated by `notify`.
 
 5. **Defaults.** A plain write (no `readAt`) is last-writer-wins with **no**
    check. A guarded write with `readAt` but no `onStale` defaults to `reject`
@@ -202,7 +202,7 @@ What the convention **guarantees**, and where it **stops**:
 These are deliberately left open; they change behavior and are the user's call.
 
 - **Default disposition for agents.** Should an agent-participant guarded write
-  default to `flag` (philosophy-aligned: surface, don't force) instead of
+  default to `notify` (philosophy-aligned: surface, don't overwrite) instead of
   `reject` (back-compat)? Trade-off: alignment vs. a behavior change for existing
   agent callers.
 - **Read-deps through the policy seam.** Should read-set conflicts also pass

package/docs/coordination.md

@@ -473,6 +473,18 @@ Each beat's answer carries two more things:
   the lease. Durable progress belongs in the data itself — write a row, and
   every subscriber already sees it.
 
+Cooperative yield has a server-side backstop your deployment can turn on: a
+**cumulative-hold ceiling**. Left unset — the default — a holder that keeps
+beating holds the row as long as it likes, and the line behind it depends on
+that holder reading `queueDepth` and releasing of its own accord. With a ceiling
+configured for a model, a holder that runs past its fair share *while contenders
+are queued* is preempted at the server: its next beat comes back `claim_lost`
+(reason `preempted`) — the same loss you already handle, so abandon or re-claim,
+and any write attempted under the old lease is fenced regardless. A holder with
+no one waiting is never preempted, however long it runs. It is the same idea as
+an SQS message that cannot stay invisible past a hard cap however often its lock
+is refreshed, narrowed here to bite only under real contention.
+
 Works identically on both transports: the realtime client sends a
 `claim_heartbeat` frame; the HTTP client posts
 `POST /api/v1/models/{model}/{id}/claim/heartbeat` (`{ ttl?, claimId?, details? }`).
@@ -603,7 +615,7 @@ inspect the `code`.
 
 | error | `code` | thrown when | carries |
 |---|---|---|---|
-| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away — the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, or was revoked — while you were holding or waiting. | `claims?` |
+| `AbloClaimedError` | `claim_lost` | A held/queued claim was taken away — the holder disconnected (reaped on the keepalive cycle), went silent past its TTL, was revoked, or was preempted (a privileged reorder, or a configured cumulative-hold ceiling reached while contenders waited) — while you were holding or waiting. | `claims?` |
 | `AbloClaimedError` | `claim_queued` | **HTTP transport only.** A contended `claim` (default `queue: true`) could not block-wait for the lease (no socket), so it rejected immediately instead of queueing. Retryable — re-attempt the claim. | `claims?` |
 | `AbloClaimedError` | `grant_timeout` | The optional `timeoutMs` elapsed while you were still queued for a grant. | `claims?` |
 | `AbloClaimedError` | `queue_too_deep` | `claim` was passed `maxQueueDepth` and the wait line was already that deep when you tried to join — fail-fast instead of waiting. | `claims?` |

package/docs/data-sources.md

@@ -20,12 +20,12 @@ exactly that.
 
 Connecting sets up two capabilities on your Postgres: **logical replication**, so
 Ablo can read and confirm, and a **scoped DML role**, so Ablo can write. `ablo
-connect` prints the exact SQL. `ablo connect --apply` runs it for you.
+connect` prints the exact SQL. `ablo connect apply` runs it for you.
 
 ## Connect in one command
 
 ```bash
-npx ablo connect --apply --url postgres://admin:...@host:5432/db
+npx ablo connect apply --url postgres://admin:...@host:5432/db
 ```
 
 Pass an admin connection string with `--url` and it creates the publication, the
@@ -34,7 +34,7 @@ both scoped roles with Ablo, and proves the setup by reconnecting and reading ba
 The admin credential is used on this machine only and never persisted — nothing is
 written to your `.env`, which keeps holding only `ABLO_API_KEY`. Pass `--show-sql`
 to see every statement first, or drop `--apply` to print the SQL and run it
-yourself. Rotate the scoped passwords any time with `ablo connect --rotate`.
+yourself. Rotate the scoped passwords any time with `ablo connect rotate`.
 
 The rest of this page is what that command sets up, step by step, for when you want
 to run it by hand or review exactly what changes.
@@ -52,7 +52,7 @@ ALTER SYSTEM SET wal_level = 'logical';
 `wal_level` is **not reloadable** — you must **restart Postgres** for it to take
 effect. On Amazon RDS / Aurora you can't `ALTER SYSTEM`; set
 `rds.logical_replication = 1` in the instance's parameter group instead, then
-reboot. (`ablo connect --apply` attempts this for you and, where a managed
+reboot. (`ablo connect apply` attempts this for you and, where a managed
 provider refuses, hands you the one remaining step.)
 
 ### 2. Run `ablo connect` for the publication and roles
@@ -101,44 +101,46 @@ Run it against your database as a superuser or the DB owner. It creates:
 The **replication slot** is created and owned by Ablo's runtime when it first
 subscribes — you don't pre-create it.
 
-### 3. Validate with `ablo connect --check`
+### 3. Register the database with Ablo
 
-Put the replication role's connection string in `DATABASE_URL`, then verify the
-database is replication-ready:
+`ablo connect apply` already did this. If you ran the SQL by hand instead, hand
+Ablo both scoped connection strings once — the replication role it reads and
+confirms through, and the writer role it lands your rows through. Set them just
+long enough to register:
 
 ```bash
-npx ablo connect --check
+export ABLO_REPLICATION_DATABASE_URL=...   # the replication role
+export ABLO_WRITE_DATABASE_URL=...         # the writer role
+npx ablo connect register
 ```
 
-It checks the four invariants and prints a green checklist or the precise per-item
-fix:
+`--register` posts them to Ablo, which holds them encrypted and uses them to read
+and write your database. Ablo holds them from here, so you can drop both from your
+environment — your app keeps only `ABLO_API_KEY`. The role passwords are generated
+for you and never printed; rotate them any time with `ablo connect rotate`. After
+this, Ablo does all the connecting.
+
+### 4. Verify readiness with `ablo connect check`
+
+```bash
+npx ablo connect check
+```
+
+`--check` needs only `ABLO_API_KEY`. It asks Ablo to check the database it now
+holds, from the same infrastructure replication runs on, and prints a green
+checklist or the precise per-item fix:
 
 - `wal_level` is `logical`
 - the `ablo_publication` publication exists
 - the replication role has the `REPLICATION` attribute
 - every published table has a usable `REPLICA IDENTITY` (a primary key, or
   `REPLICA IDENTITY FULL`) so `UPDATE`/`DELETE` can replicate
+- the writer role is DML-ready — scoped, non-superuser, with the idempotency
+  ledger in place
 
-`--check` reads the two scoped roles from `ABLO_REPLICATION_DATABASE_URL` and
-`ABLO_WRITE_DATABASE_URL` (the `ABLO_`-namespaced names keep a replication-only
-credential from ever landing in the generic `DATABASE_URL` your ORM reads).
-Re-run it until every item is green.
-
-### 4. Register the two roles with Ablo
-
-`ablo connect --apply` already did this. If you ran the SQL by hand instead, hand
-Ablo both connection strings — the replication role it reads and confirms through,
-and the writer role it lands your rows through:
-
-```bash
-npx ablo connect --register
-```
-
-This is out of band and happens once. `--register` reads the two scoped connection
-strings from `ABLO_REPLICATION_DATABASE_URL` and `ABLO_WRITE_DATABASE_URL` and
-posts them to Ablo, which holds them encrypted and uses them to read and write your
-database. The role passwords are generated for you and never printed — rotate them
-any time with `ablo connect --rotate`. After this, Ablo does all the connecting.
+Because Ablo checks from its own network, a database your own machine can't reach —
+IPv6-only, IP-allowlisted, behind a VPN — still verifies. Re-run it until every
+item is green.
 
 Your **app** holds only the API key — never a connection string:
 
@@ -172,10 +174,10 @@ landed:
 
 ```ts
 // Enters the chokepoint (claims, ordering, idempotency), lands in your Postgres.
-await ablo.weatherReports.update('report_stockholm', { high: 21 });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 } });
 
 // Block until your database has it and the WAL echo confirms.
-await ablo.weatherReports.update('report_stockholm', { high: 21 }, { wait: 'confirmed' });
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 }, wait: 'confirmed' });
 
 // Reads are live off the same stream.
 const report = ablo.weatherReports.get('report_stockholm');

package/docs/examples/agent-human.md

@@ -50,11 +50,11 @@ export async function markReady(reportId: string) {
     // queue: false → don't queue behind a current holder. If a human already
     // holds the row, claim rejects with AbloClaimedError (caught below), so the
     // agent yields instead of waiting. Omit it, or pass queue: true, to queue
-    // behind them. reason → the label observers see while we work.
+    // behind them. description → the label observers see while we work.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
       queue: false,
-      reason: 'marking_ready',
+      description: 'marking_ready',
     });
     const claimed = claim.data;
 

package/docs/examples/ai-sdk-tool.md

@@ -43,7 +43,7 @@ const updateReport = tool({
     // The claim is released automatically when it goes out of scope.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
-      reason: 'editing',
+      description: 'editing',
       ttl: '2m',
     });
     const claimed = claim.data;

package/docs/examples/nextjs.md

@@ -58,7 +58,7 @@ export async function markReady(id: string) {
   await using claim = await ablo.weatherReports.claim({
     id,
     queue: false,
-    reason: 'marking_ready',
+    description: 'marking_ready',
   });
   const claimed = claim.data;
 

package/docs/examples/server-agent.md

@@ -39,7 +39,7 @@ export async function completeReport(reportId: string) {
   await using claim = await ablo.weatherReports.claim({
     id: reportId,
     queue: false,
-    reason: 'completing',
+    description: 'completing',
   });
   const claimed = claim.data;
 
@@ -62,7 +62,7 @@ The two options on the claim:
 
 - `queue: false` — skip this record if another claim is already in progress,
   rather than queueing behind it. (The default queues.)
-- `reason: 'completing'` — a human-readable label for what your worker is doing,
+- `description: 'completing'` — a human-readable label for what your worker is doing,
   visible to anyone reading `claim.state({ id })`.
 
 Because the worker uses the same schema and `claim()` as the UI, its writes sync

package/docs/groups.md

@@ -0,0 +1,160 @@
+# Change Propagation
+
+> How a change to one row reaches the rows and actors that depend on it, and how
+> to keep a chain of dependent work fresh. This is the propagation half of sync
+> groups; [`identity.md`](./identity.md) is the access half (who may read a
+> group), and [`concurrency-convention.md`](./concurrency-convention.md) is the
+> convention this rests on.
+
+---
+
+## Start from the problem
+
+An agent reads deck `A` to write slide `B`. A moment later it reads `B` to write
+layer `C`. Between those steps someone else edits `A`. The agent is now building
+`C` on a premise that has moved — and nothing about writing `C` looks wrong in
+isolation. That is stale context, and it is the thing sync groups let you catch.
+
+The recipe is one field on the commit: declare the group you read as a premise,
+and say what should happen if it moved.
+
+```ts
+// The agent read everything under deck:abc to compose this write.
+await ablo.layers.update({
+  id: 'layer-C',
+  data: { text: revised },
+  reads: [{ group: 'deck:abc', readAt: watermark, onStale: 'notify' }],
+});
+```
+
+At commit, inside the write transaction, the engine asks a single question: *did
+any delta routed to `deck:abc` land after `watermark`?* If nothing moved, the
+write applies. If something moved, `onStale` decides — `notify` holds the write
+and hands the agent a `StaleNotification` naming the group, so it re-reads
+`deck:abc` and regenerates; `reject` aborts the batch with a `409`. The agent
+never persists work built on a premise it can no longer see.
+
+---
+
+## Three ways a change reaches other rows
+
+"A affects B and C" means three different things. The engine does the first two
+for you and leaves the third to you — on purpose.
+
+**Routing — who hears about a change.** Every row belongs to one or more sync
+groups, and a write fans out to all of them. A row also inherits its ancestors'
+groups: editing a layer stamps the delta with `layer:…`, `slide:…`, *and*
+`deck:…`, so everyone watching the deck sees the layer move. This is delivery,
+resolved by walking the ownership tree at commit time. It routes the change; it
+never recomputes a value.
+
+**Structural cascade — what disappears with a change.** Deleting a deck removes
+its slides and layers. The database does that through `ON DELETE CASCADE`, but a
+database-level cascade emits no delta, so open clients would quietly hold rows
+that no longer exist. The engine closes that gap: before the delete it snapshots
+the subtree and emits a tombstone for each descendant, routed to the right
+group. Watchers see the whole subtree vanish.
+
+**Value recomputation — what a change implies for derived state.** If `B` holds a
+number rolled up from `A`, the engine does not recompute `B` when `A` changes. It
+surfaces that `A` moved and lets the actor decide what `B` should become. This is
+the non-coercion principle: coordinate and report, resolve nothing by fiat.
+Merging derived state is a judgment call, and for an agent in the loop that
+judgment is the whole point.
+
+---
+
+## The chain: A → B → C
+
+Model a dependency as shared group membership. Put `A` and `B` in one group, `B`
+and `C` in another, and you have wired the edges of a chain. What travels along
+those edges is a *signal*, one hop at a time — not a recomputation.
+
+```
+A writes ──▶ group {A,B} ──▶ B hears it
+                                  │  B decides, B writes
+                                  ▼
+                             group {B,C} ──▶ C hears it
+```
+
+A's delta lands in `{A,B}` and stops there. `C` is not in that group, so `C`
+learns nothing from A directly. `C` advances only when **B itself writes** and
+that new delta lands in `{B,C}`. `B` is the translator: it takes "A moved,"
+decides what that means for its own state, commits, and *its* commit is what
+reaches `C`.
+
+The direction matters. The signal flows forward, A to B to C, and each hop is a
+real write an actor chose to make. The engine supplies the edges (group
+membership) and a stale signal on each edge (the read-dependency check); the
+actors are the runtime that walks them. It is closer to a spreadsheet an analyst
+recalculates cell by cell than to a reactive engine that recomputes the whole
+column for you.
+
+Two consequences worth designing around:
+
+- **The chain runs as fast as actors react.** If `B` never acts on its signal,
+  the chain stops at `B` and `C` stays as it was. Freshness is an actor
+  responsibility; the engine guarantees the signal, not the follow-through.
+- **Cycles don't settle themselves.** If `C` writes back to `A`, each hop is a
+  separate commit with its own stale check, and nothing damps the oscillation.
+  Keep the dependency graph acyclic, or give one actor the job of reaching a
+  fixpoint. Convergence lives above the engine.
+
+---
+
+## Declaring a read premise
+
+A read-dependency is a premise for the *whole* batch: its disposition governs
+every write in the commit, not just one operation. You choose the granularity per
+entry.
+
+```ts
+reads: [
+  { group: 'deck:abc', readAt: N, onStale: 'notify' },      // did anything in the deck move?
+  { model: 'Slide', id: 's-1', readAt: N, fields: ['title'] }, // did this row (this field) move?
+]
+```
+
+A **group** premise asks "did anything I was watching change?" — the native
+Ablo granularity, and the right tool for the chain above. A **row** premise is
+literal: this object, optionally these fields. A row premise with `fields`
+conflicts only on real field overlap, so two actors editing disjoint fields of
+the same row don't collide.
+
+`onStale` has three settings, defaulting to `reject`:
+
+- **`notify`** holds every write in the batch and returns a `StaleNotification`.
+  For a group premise it carries the group name and the new watermark
+  (`observedSyncId`); re-read the group at that point and regenerate. This is the
+  setting a chain wants — the actor gets the truth and resolves it.
+- **`reject`** aborts the batch with a `stale_context` error (`409`). The right
+  default when there is nothing to reconcile and the write should simply not
+  land.
+- **`overwrite`** skips the check and lets the write land — last-write-wins, the
+  explicit escape hatch.
+
+---
+
+## Sizing groups
+
+A group is the unit of both delivery and staleness, so its size is a real
+tradeoff. A change fans out to every subscriber of every group it touches, and a
+group premise fires when *anything* in the group moves — so a group that is too
+broad wakes actors for changes they don't care about, and one that is too narrow
+misses the dependency you meant to track.
+
+The rule of thumb: **make a group the smallest set of rows that must stay
+mutually consistent.** A deck and its slides belong together because editing one
+changes what the others mean; two unrelated decks do not. Reach for finer,
+overlapping groups when you genuinely have a dependency chain to track, and keep
+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 read-set, and the notification — is
+  [`concurrency-convention.md`](./concurrency-convention.md) (§4 and §5).
+- **The mechanics** — the three coordination layers underneath — are
+  [`coordination.md`](./coordination.md).

package/docs/guarantees.md

@@ -66,10 +66,8 @@ snapshot, the server rejects the write instead of applying stale reasoning.
 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 not yet available.
+- `overwrite` applies the write without stale protection.
+- `notify` accepts the write and marks it for product review.
 
 ## Claim Coordination
 
@@ -148,9 +146,13 @@ separates workflow or deployment lanes sharing the same store.
 
 ## Storage Boundary
 
-Ablo does not need a customer database URL. When your own database is canonical,
-Ablo calls a signed Data Source endpoint and records the coordination result for
-receipts, realtime fanout, and audit. See [Connect Your Database](./data-sources.md).
+Your rows live in your database; Ablo holds only the transaction log and the
+coordination state. Writes enter Ablo's commit chokepoint and land in your
+Postgres through a scoped writer role, and the WAL echo confirms them
+(`queued` → `confirmed`). For a database that can't grant replication, Ablo
+forwards the write to a signed Data Source endpoint instead — the marked
+fallback. Either way Ablo never holds a database connection string. See
+[Connect Your Database](./data-sources.md).
 
 ## Writes
 

package/docs/how-it-works.md

@@ -0,0 +1,110 @@
+# How Ablo Works
+
+You write through Ablo, and Ablo writes to your Postgres. That one sentence is the
+whole model — everything below explains what it means and how to use it.
+
+```ts
+// You call Ablo. Ablo lands the change in your database and confirms it.
+await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confirmed' });
+
+// Reads come back live, kept current from your database.
+const task = ablo.tasks.get('task_42');
+```
+
+## The mental model — read this once
+
+Ablo is a **coordination layer in front of your Postgres**. Humans, agents, and
+background jobs 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
+  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.
+- **Your database confirms the write.** Ablo tails your write-ahead log (WAL). When
+  the row it wrote shows up there, the receipt is promoted to `confirmed`. So your
+  database, not Ablo, is the source of truth for row state — the WAL echo is how
+  Ablo *confirms*, not how it writes.
+- **Reads are live.** Ablo serves current state and keeps every connected client up
+  to date off that same stream.
+- **Ablo stores only the log.** Ablo holds the ordered transaction log
+  (`sync_deltas`) and the coordination state — the claims, the ordering, the
+  watermarks. Your rows live in your database. Ablo runs no DDL and owns no schema;
+  your migration tool stays in charge of the shape of your database.
+
+That's the shape: **you write through Ablo → it lands in your Postgres → the WAL
+echo confirms it → everyone connected sees it live.**
+
+## 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
+  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
+  models, same code, a different database behind them.
+- **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.
+
+## Use it end to end
+
+```bash
+# 1. Install and scaffold.
+npm install @abloatai/ablo
+npx ablo init
+
+# 2. Push your schema (the models humans and agents edit together).
+npx ablo push
+
+# 3. Connect your database — one command, admin credential used once and discarded.
+npx ablo connect apply --url postgres://admin:...@host:5432/db
+```
+
+```bash
+# Your app's environment holds only the API key — never a connection string.
+ABLO_API_KEY=sk_live_...
+```
+
+```ts
+// 4. Build the client once.
+import Ablo from '@abloatai/ablo';
+import { schema } from './ablo/schema';
+export const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+// 5. Write through Ablo. It lands in your Postgres; wait: 'confirmed' blocks
+//    until the WAL echo proves the row is there.
+await ablo.tasks.update({ id: 'task_42', data: { status: 'done' }, wait: 'confirmed' });
+
+// 6. Read — live, no fetch loop.
+const task = ablo.tasks.get('task_42');
+
+// 7. Coordinate when more than one actor can touch a row. Hold a claim and Ablo
+//    serializes writes on that key against everyone else; read after claiming,
+//    then write. The lease releases automatically at the end of the scope.
+await using _hold = await ablo.tasks.claim('task_42');
+const latest = ablo.tasks.get('task_42'); // read after claiming, not from memory
+await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
+```
+
+## Reading the architecture correctly
+
+The model changed once (ADR 0010), and older material described the earlier one.
+If you've read that a customer's app keeps writing while Ablo only tails the WAL,
+here is the current, correct reading:
+
+- **"Ablo tails the WAL."** True — to *confirm* your writes and serve live reads.
+  It is not the write path. You write **through** Ablo.
+- **"Ablo is out of the write path."** Not anymore. Ablo is the write chokepoint;
+  every write flows through its coordination and then into your database.
+- **"Ablo holds my rows."** Only in the no-database-yet sandbox. Once you connect a
+  database, your rows live in *your* Postgres — Ablo keeps just the log.
+- **"Ablo migrates my schema."** No. Ablo writes rows through a scoped role and runs
+  no DDL; your migrations own the shape of your database.
+
+For the setup details, see [Connect Your Database](./data-sources.md). For the
+coordination loop, see [Concurrency Convention](./concurrency-convention.md). For
+what `queued` and `confirmed` guarantee, see [Guarantees](./guarantees.md).